feat(sessions): port GET /api/sessions/[sessionId] from open-agents (Phase 2.4)

[sweetmantech]

Summary

First route in the route-by-route cutover plan (Phase 2.4 / new strategy). Ports the simplest endpoint open-agents' frontend hits — GET /api/sessions/[sessionId] — into api with byte-identical response shape so the frontend can cut over with zero changes.

Context

Per the strategy shift discussed: instead of building agent runner + workflow + routes in isolation and hoping they integrate, we let the open-agents frontend drive what gets ported, in what order. The frontend becomes the spec; each route ported is validated end-to-end against a real consumer.

This PR is the smallest provable first port. Everything that follows uses the same shape.

Why this route first

Property	Value
Backend deps	DB only — no agent runner, no Vercel Workflow, no sandbox runtime
Schema deps	`sessions` table — already migrated in database#20
Frontend usage	hit on session-detail page navigation
Blast radius	smallest possible — proves the pattern with minimal new code

Files

File	Purpose
`lib/supabase/sessions/selectSession.ts`	Single-row select helper + `SessionRow` type. Hand-typed pending `types/database.types.ts` regen (flagged in code comment)
`app/api/sessions/[sessionId]/route.ts`	`GET` handler matching open-agents' response shape exactly
`app/api/sessions/[sessionId]/tests/route.test.ts`	5 tests (auth fail, not-found, forbidden, happy path, OPTIONS)

Auth + response codes

• Auth: `validateAuthContext` (Privy Bearer or x-api-key). Same as every other api route.
• 200 — happy path with `{ session }`
• 401 — no auth
• 403 — session exists but not owned by authenticated account
• 404 — session not found

Wire-format translation

The Supabase row is snake_case (`account_id`, `repo_owner`, `is_new_branch`, …). The open-agents frontend expects camelCase (`userId`, `repoOwner`, `isNewBranch`, …). Translation lives at the route boundary in `toSessionResponse()` so:

• Schema stays natural (`account_id` is the right name for "FK to accounts table")
• Frontend stays unchanged (`userId` is what its hooks consume today)
• Translation is one easy-to-find function to delete when chat absorbs this UI and we can switch to schema-natural naming

Notably the response field is `userId` (the open-agents term) sourced from `account_id` (api's term). Same value, two names — kept compatible during the cutover window.

Verification

Check	Result
`pnpm lint:check`	✅ clean
`pnpm test`	✅ 2379/2379 pass (was 2374 — +5 from new route tests)

What's NOT in scope yet

• Frontend cutover — separate PR in the open-agents repo: point its frontend at api's URL for this one route. Validates end-to-end. Don't merge that until this api route is in test/main.
• PATCH / DELETE for the same path — open-agents has them too, but they're write paths; do them after the read works in prod.
• Types regen — `SessionRow` is hand-typed here. Should be replaced with `Tables<"sessions">` once `pnpm update-types` is run against an environment that has the migrations applied.

Up next in the chain

After this lands and the frontend cutover validates:

• `GET /api/sessions/[id]/chats` — list chats for a session (single-table read)
• `GET /api/sessions/[id]/chats/[chatId]` — read one chat (single-table read)
• `GET /api/sessions` — list sessions with unread (needs a Postgres RPC for the multi-table aggregation; bigger PR)

🤖 Generated with Claude Code

---

Summary by cubic

Ports GET /api/sessions/[sessionId] with the same camelCase response as open-agents so the frontend can switch over without changes. First route in Phase 2.4’s route-by-route cutover.

• New Features

  • Added GET and OPTIONS in app/api/sessions/[sessionId]/route.ts; delegates to getSessionByIdHandler; sets dynamic="force-dynamic", fetchCache="force-no-store", and revalidate=0.
  • Auth via validateAuthContext (Privy Bearer or x-api-key) with ownership check; status codes: 200 { session }, 401, 403, 404; JSON errors via { status: "error", error: "..." }; CORS via getCorsHeaders.
  • 5 tests cover 401/404/403/200 and OPTIONS.

• Refactors

  • Introduced lib/sessions/getSessionByIdHandler.ts; reads via selectSessions({ id }), enforces account_id ownership, and maps rows with toSessionResponse for camelCase output.

^{Written for commit e6aaba9. Summary will update on new commits.}

Summary by CodeRabbit

Release Notes

• New Features
  • Added an API endpoint to retrieve session details by session ID, with authentication and authorization checks to ensure users can only access their own sessions.

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Actions	Updated (UTC)
api	Ready	Preview	May 4, 2026 11:54pm

[coderabbitai]

Warning

Rate limit exceeded

@sweetmantech has exceeded the limit for the number of commits that can be reviewed per hour. Please wait 5 minutes and 49 seconds before requesting another review.

To keep reviews running without waiting, you can enable usage-based add-on for your organization. This allows additional reviews beyond the hourly cap. Account admins can enable it under billing.

⌛ How to resolve this issue?

After the wait time has elapsed, a review can be triggered using the @coderabbitai review command as a PR comment. Alternatively, push new commits to this PR.

We recommend that you space out your commits to avoid hitting the rate limit.

🚦 How do rate limits work?

CodeRabbit enforces hourly rate limits for each developer per organization.

Our paid plans have higher rate limits than the trial, open-source and free plans. In all cases, we re-allow further reviews after a brief timeout.

Please see our FAQ for further information.

ℹ️ Review info

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: CHILL

Plan: Pro

Run ID: 766082af-1746-45b6-846a-2c3aa7a3a405

📥 Commits

Reviewing files that changed from the base of the PR and between 00e2823 and e6aaba9.

⛔ Files ignored due to path filters (1)

• app/api/sessions/[sessionId]/__tests__/route.test.ts is excluded by !**/*.test.*, !**/__tests__/** and included by app/**

📒 Files selected for processing (2)

• app/api/sessions/[sessionId]/route.ts
• lib/sessions/getSessionByIdHandler.ts

📝 Walkthrough

Walkthrough

A new API endpoint retrieves sessions by ID with authentication and authorization checks. The implementation includes a database query function, response transformation layer, handler with auth validation and error handling, and a Next.js route with CORS support and no-cache directives.

Changes

Session Retrieval Endpoint

Layer / File(s)	Summary
Data Access lib/supabase/sessions/selectSession.ts	selectSession(sessionId) queries the Supabase sessions table by ID and returns the row or null on error.
Response Transformation lib/sessions/toSessionResponse.ts	toSessionResponse(row) converts Supabase snake_case row fields (account_id, repo_owner, clone_url, etc.) to camelCase API response properties.
Handler & Orchestration lib/sessions/getSessionByIdHandler.ts	getSessionByIdHandler validates auth context, fetches the session, enforces account ownership with 403 for mismatches, returns 404 when absent, and wraps responses with CORS headers.
Route Registration & Caching app/api/sessions/[sessionId]/route.ts	Exports GET and OPTIONS handlers; extracts sessionId from route params, delegates to getSessionByIdHandler, and applies force-dynamic, force-no-store, and revalidate = 0 directives.

Sequence Diagram

sequenceDiagram
    participant Client
    participant Route as Route Handler<br/>(route.ts)
    participant Auth as Auth Validation
    participant DB as Database<br/>(selectSession)
    participant Transform as Response<br/>Transformer
    participant Response as HTTP Response

    Client->>Route: GET /api/sessions/{sessionId}
    alt Preflight
        Route->>Response: OPTIONS → 200 + CORS headers
        Response->>Client: 200 OK
    else Fetch Session
        Route->>Auth: Validate auth context
        alt Auth Invalid
            Auth->>Response: Return auth error
        else Auth Valid
            Route->>DB: selectSession(sessionId)
            DB->>Response: Session row or null
            alt Session Not Found
                Response->>Route: 404 error response
            else Session Found
                alt Account Mismatch
                    Response->>Route: 403 Forbidden
                else Account Match
                    Route->>Transform: toSessionResponse(row)
                    Transform->>Route: Transformed session object
                    Route->>Response: 200 + session + CORS headers
                end
            end
        end
        Response->>Client: Response with headers
    end

Loading

Estimated Code Review Effort

🎯 3 (Moderate) | ⏱️ ~20 minutes

Poem

🔐 A session seeketh by its ID,
Through auth and account checks it flows with glee,
Snake_case bends to camelCase delight,
CORS headers guard it left and right,
One endpoint born to retrieve with care! 📋

🚥 Pre-merge checks | ✅ 3

✅ Passed checks (3 passed)

Check name	Status	Explanation
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Solid & Clean Code	✅ Passed	PR demonstrates excellent SOLID and Clean Code adherence with single-responsibility functions, descriptive naming matching filenames, proper separation of concerns across database, transformation, and HTTP layers, and clean error handling patterns.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch feat/port-get-session-route

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

[cubic-dev-ai]

2 issues found across 3 files

Confidence score: 3/5

• Potential user-facing error handling issue in app/api/sessions/[sessionId]/route.ts: database failures are surfaced as 404s instead of 500s, which can mask real server problems.
• Some risk remains due to the concrete error-handling behavior change needed, though it's localized and fixable.
• Pay close attention to app/api/sessions/[sessionId]/route.ts - distinguish DB failures from missing rows to avoid misleading 404s.

Prompt for AI agents (unresolved issues)

Check if these issues are valid — if so, understand the root cause of each and fix them. If appropriate, use sub-agents to investigate and fix each issue separately.


<file name="app/api/sessions/[sessionId]/__tests__/route.test.ts">

<violation number="1" location="app/api/sessions/[sessionId]/__tests__/route.test.ts:1">
P2: Custom agent: **Enforce Clear Code Style and Maintainability Practices**

New test file exceeds the repository's 100-line file-size limit.</violation>
</file>

<file name="app/api/sessions/[sessionId]/route.ts">

<violation number="1" location="app/api/sessions/[sessionId]/route.ts:85">
P2: `selectSession` errors are currently surfaced as 404 "Session not found" because this route treats any `null` row as not-found. Distinguish DB failures from missing rows and return a 500 with a generic message.

(Based on your team's feedback about safe 500 error handling in API handlers.) [FEEDBACK_USED]</violation>
</file>

Architecture diagram

sequenceDiagram
    participant Client as Frontend (Open-Agents)
    participant API as Session Route (API)
    participant Auth as validateAuthContext
    participant DB as Supabase (Sessions Table)

    Note over Client, DB: NEW: GET /api/sessions/[sessionId] Flow

    Client->>API: GET /api/sessions/[sessionId]
    Note right of Client: Headers: Privy Bearer or x-api-key

    API->>Auth: validateAuthContext(request)
    alt Auth Failed
        Auth-->>API: NextResponse (401 Unauthorized)
        API-->>Client: 401 Unauthorized
    else Auth Success
        Auth-->>API: { accountId, authToken }
        
        API->>DB: NEW: selectSession(sessionId)
        DB-->>API: SessionRow (snake_case) or null

        alt Session Not Found
            API-->>Client: 404 Not Found
        else Session Exists
            API->>API: Check ownership (row.account_id === auth.accountId)
            
            alt Not Owner
                API-->>Client: 403 Forbidden
            else Is Owner
                API->>API: NEW: toSessionResponse(row)
                Note right of API: Translates snake_case DB fields<br/>to camelCase (e.g. account_id -> userId)
                API-->>Client: 200 OK (JSON { session })
            end
        end
    end

    Note over API, Client: Includes CORS headers in all responses via getCorsHeaders()

Loading

_{Reply with feedback, questions, or to request a fix. Tag @cubic-dev-ai to re-run a review.}

[cubic-dev-ai]

P2: Custom agent: Enforce Clear Code Style and Maintainability Practices

New test file exceeds the repository's 100-line file-size limit.

Prompt for AI agents

Check if this issue is valid — if so, understand the root cause and fix it. At app/api/sessions/[sessionId]/__tests__/route.test.ts, line 1:

<comment>New test file exceeds the repository's 100-line file-size limit.</comment>

<file context>
@@ -0,0 +1,153 @@
+import { describe, it, expect, vi, beforeEach } from "vitest";
+import { NextRequest, NextResponse } from "next/server";
+import { GET, OPTIONS } from "../route";
</file context>

[cubic-dev-ai]

P2: selectSession errors are currently surfaced as 404 "Session not found" because this route treats any null row as not-found. Distinguish DB failures from missing rows and return a 500 with a generic message.

(Based on your team's feedback about safe 500 error handling in API handlers.)

View Feedback

Prompt for AI agents

Check if this issue is valid — if so, understand the root cause and fix it. At app/api/sessions/[sessionId]/route.ts, line 85:

<comment>`selectSession` errors are currently surfaced as 404 "Session not found" because this route treats any `null` row as not-found. Distinguish DB failures from missing rows and return a 500 with a generic message.

(Based on your team's feedback about safe 500 error handling in API handlers.) </comment>

<file context>
@@ -0,0 +1,106 @@
+  }
+
+  const { sessionId } = await options.params;
+  const row = await selectSession(sessionId);
+
+  if (!row) {
</file context>

[sweetmantech]

SRP - new lib file for toSessionResponse.ts

[sweetmantech]

DRY -

• actual: manually defining response type
• required: use existing db schema type, matching all other supabase libs.

[coderabbitai]

🧹 Nitpick comments (2)

app/api/sessions/[sessionId]/route.ts (2)

40-42: 💤 Low value

force-dynamic / revalidate = 0 directives are redundant under Next.js 16.

Under Next.js 16's Cache Components model, caching is entirely opt-in, and all dynamic code in any page, layout, or API route executes at request time by default. The three cache-busting directives are therefore no-ops in this version, though they cause no harm and do signal explicit intent.

No action required, but you can remove them once Next.js 16 is the confirmed minimum version for this codebase.

🤖 Prompt for AI Agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In `@app/api/sessions/`[sessionId]/route.ts around lines 40 - 42, The exported
cache-control directives dynamic, fetchCache and revalidate in route.ts (export
const dynamic = "force-dynamic"; export const fetchCache = "force-no-store";
export const revalidate = 0;) are redundant under Next.js 16; remove those three
exports from the file (delete the symbols dynamic, fetchCache and revalidate) so
the API route relies on the framework's default request-time behavior once
Next.js 16 is the confirmed minimum.

---

32-38: ⚡ Quick win

Add Zod validation for sessionId per the coding guidelines.

The sessionId path parameter passes directly to the DB query without any schema validation. An invalid/malformed ID currently returns 404 instead of a semantically correct 400. The coding guideline requires Zod validation for all API input.

✨ Proposed fix — validate in the route before delegating

+import { z } from "zod";
+
+const SessionIdSchema = z.string().uuid();
+
 export async function GET(
   request: NextRequest,
   options: { params: Promise<{ sessionId: string }> },
 ) {
   const { sessionId } = await options.params;
+  const parsed = SessionIdSchema.safeParse(sessionId);
+  if (!parsed.success) {
+    return NextResponse.json({ error: "Invalid session ID" }, { status: 400 });
+  }
-  return getSessionByIdHandler(request, sessionId);
+  return getSessionByIdHandler(request, parsed.data);
 }

Alternatively, validation can live inside getSessionByIdHandler itself if it is reused across routes.

As per coding guidelines: "All API endpoints should use a validate function for input parsing using Zod for schema validation."

🤖 Prompt for AI Agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In `@app/api/sessions/`[sessionId]/route.ts around lines 32 - 38, The route
handler GET currently forwards the raw sessionId directly to
getSessionByIdHandler without schema checks; add Zod validation for the path
param before delegating so malformed IDs return 400. Create/consume a Zod schema
(e.g., z.string().uuid() or appropriate pattern) and run validate/parse on the
extracted sessionId inside GET, returning a 400 response on failure and only
calling getSessionByIdHandler(request, sessionId) when validation succeeds;
alternatively move the same validation into getSessionByIdHandler if it must be
reused.

🤖 Prompt for all review comments with AI agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Nitpick comments:
In `@app/api/sessions/`[sessionId]/route.ts:
- Around line 40-42: The exported cache-control directives dynamic, fetchCache
and revalidate in route.ts (export const dynamic = "force-dynamic"; export const
fetchCache = "force-no-store"; export const revalidate = 0;) are redundant under
Next.js 16; remove those three exports from the file (delete the symbols
dynamic, fetchCache and revalidate) so the API route relies on the framework's
default request-time behavior once Next.js 16 is the confirmed minimum.
- Around line 32-38: The route handler GET currently forwards the raw sessionId
directly to getSessionByIdHandler without schema checks; add Zod validation for
the path param before delegating so malformed IDs return 400. Create/consume a
Zod schema (e.g., z.string().uuid() or appropriate pattern) and run
validate/parse on the extracted sessionId inside GET, returning a 400 response
on failure and only calling getSessionByIdHandler(request, sessionId) when
validation succeeds; alternatively move the same validation into
getSessionByIdHandler if it must be reused.

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: CHILL

Plan: Pro

Run ID: 214e687c-3916-4fc3-be56-cd2eba560d21

📥 Commits

Reviewing files that changed from the base of the PR and between 97724c4 and 00e2823.

⛔ Files ignored due to path filters (2)

• app/api/sessions/[sessionId]/__tests__/route.test.ts is excluded by !**/*.test.*, !**/__tests__/** and included by app/**
• types/database.types.ts is excluded by none and included by none

📒 Files selected for processing (4)

• app/api/sessions/[sessionId]/route.ts
• lib/sessions/getSessionByIdHandler.ts
• lib/sessions/toSessionResponse.ts
• lib/supabase/sessions/selectSession.ts

[cubic-dev-ai]

0 issues found across 6 files (changes from recent commits).

_{Requires human review: Auto-approval blocked by 2 unresolved issues from previous reviews.}

[cubic-dev-ai]

0 issues found across 2 files (changes from recent commits).

_{Requires human review: Auto-approval blocked by 2 unresolved issues from previous reviews.}

[sweetmantech]

Preview deployment smoke test (commit e6aaba94)

Tested against https://api-git-feat-port-get-session-route-recoup.vercel.app. Reused an x-api-key issued earlier via POST /api/agents/signup on this preview's environment.

A session created during the POST PR's smoke test is still in the preview DB on the same account (2db5cda8-8b1c-4c6d-87e9-ed8f10a9757a, session id ec6c10d9-8966-4231-93ea-c1b40ba6caf1, title "Osaka"). Used that as the owned-session fixture.

T1 — 401 no auth

GET /api/sessions/ec6c10d9-8966-4231-93ea-c1b40ba6caf1 HTTP/1.1

Response:

HTTP/2 401
{"status":"error","error":"Exactly one of x-api-key or Authorization must be provided"}

✅ Matches validateAuthContext envelope.

T2 — 404 session not found

GET /api/sessions/00000000-0000-0000-0000-000000000000 HTTP/1.1
x-api-key: recoup_sk_…

Response:

HTTP/2 404
{"status":"error","error":"Session not found"}

✅ Matches docs PR #185 spec for 404 response.

T3 — 200 owned session (full Session shape)

GET /api/sessions/ec6c10d9-8966-4231-93ea-c1b40ba6caf1 HTTP/1.1
x-api-key: recoup_sk_…

Response:

HTTP/2 200

{
  "session": {
    "id": "ec6c10d9-8966-4231-93ea-c1b40ba6caf1",
    "userId": "2db5cda8-8b1c-4c6d-87e9-ed8f10a9757a",
    "title": "Osaka",
    "status": "running",
    "repoOwner": null, "repoName": null, "branch": null, "cloneUrl": null,
    "isNewBranch": false,
    "globalSkillRefs": [],
    "sandboxState": { "type": "vercel" },
    "lifecycleState": "provisioning",
    "lifecycleVersion": 0,
    "lastActivityAt": null, "sandboxExpiresAt": null, "hibernateAfter": null,
    "lifecycleRunId": null, "lifecycleError": null,
    "linesAdded": 0, "linesRemoved": 0,
    "snapshotUrl": null, "snapshotCreatedAt": null, "snapshotSizeBytes": null,
    "cachedDiff": null, "cachedDiffUpdatedAt": null,
    "createdAt": "2026-05-04T23:23:20.653727+00:00",
    "updatedAt": "2026-05-04T23:23:20.653727+00:00"
  }
}

Field-by-field check against docs PR #185 spec:

• userId (UUID) ✓, title ✓, status ✓, all repo fields nullable ✓, isNewBranch ✓
• globalSkillRefs array, sandboxState object ✓
• lifecycleState, lifecycleVersion ✓
• All nullable timestamps + nullable lifecycle fields ✓
• linesAdded / linesRemoved ✓
• All snapshot/diff fields ✓
• createdAt / updatedAt ✓

The 4 trimmed fields (autoCommitPushOverride, autoCreatePrOverride, prNumber, prStatus) correctly absent — matches the trimmed Session schema in docs.

403 cross-account ownership

Couldn't trigger live (would need a session owned by a different account). Covered by unit test app/api/sessions/[sessionId]/__tests__/route.test.ts:100-116 which mocks validateAuthContext to return accountId: "acc-uuid-OTHER" while selectSessions returns a row owned by acc-uuid-1, asserting 403 {status:"error", error:"Forbidden"}.

Unit test summary

29 tests pass (5 added by this PR, 24 existing from the POST PR). Format + lint clean.