Session Topology

The Session Topology view renders all active and recently completed sessions as a React Flow graph, showing handoff edges between agents and sub-agent trees. It is the primary tool for understanding what your fleet is doing at a glance.

The topology view is accessible from the project's Sessions section. It requires an authenticated browser session (cookie or WorkOS session) - it is not available via rsk_* Bearer tokens in the current release.

What the Graph Shows

Nodes represent individual sessions. Each node shows:

Field	Description
Agent name	Resolved from `agent_identities`; falls back to the agent ID
Agent role	`worker` · `sub-agent` · role from the agent identity
Status	`working` · `completed` · `failed` · `stopped` · `pending`
Health dot	Green / yellow / red - computed by `computeHealthSummary`
Issue identifier	The tracker issue the session is working on (e.g. `ENG-201`)
Issue title	Resolved from the Linear issue title cache (best-effort)
Cost	Estimated USD spend so far
Reserved files	Files currently locked by this session
Work type	`development` · `research` · `qa` · etc.
Model	The LLM model profile in use

Edges come from two sources:

Handoff edges - derived from work-item.handoff factory events; show which agent handed work to another
Sub-agent edges - persisted sub-agent relationships from the getSubagentsForSessions store; show parent → child dispatch trees

Decay Window

Completed and failed sessions do not disappear immediately. By default they remain on the topology for 30 minutes after their completedAt timestamp. This keeps the graph useful after a batch of issues finishes - you can see what just ran without navigating into individual sessions.

The decay window is configurable via the TOPOLOGY_DECAY_MINUTES environment variable (operator setting; defaults to 30).

Project Scoping

The ?project query parameter accepts the project slug, not the display name. Passing the project's display name returns an empty topology without an error. Use rensei project list or check the URL of your project page to find the slug.

To scope the topology to a single project, pass its slug:

GET /api/sessions/topology?project=my-project-slug

Without a project filter, the topology shows all sessions for your active org. With a project filter, the platform:

Resolves the slug to a projectId
Looks up the tracker queue keys for that project (Linear project names)
Filters Redis sessions by matching projectName against those keys
Filters DB sessions by projectId

This double-resolution ensures that sessions created before a project was fully configured are still included correctly.

If the slug does not match any project in your org, the topology returns empty nodes and edges rather than falling back to the org-wide view.

Data Sources

The topology merges data from two stores:

PostgreSQL (agent_sessions)

Authoritative session records. Provides agent identity, cost, and status. Covers up to 100 active sessions and 50 recently-completed sessions per query.

Redis (worker fleet)

Live worker state: current status, heartbeat, workType, toolCallCount, reserved files, model. Covers all statuses including queued and finalizing. Falls back gracefully when Redis is unavailable.

Sessions that appear in Redis but not yet in the DB (e.g. very fresh sessions) are included via Redis enrichment. Sessions in both stores are deduplicated by sessionId - last writer wins, with sub-agent annotations taking precedence.

API Reference

GET /api/sessions/topology

Authentication: Browser session cookie or WorkOS session (user-scoped; org context resolved from active session).

Query parameters:

Parameter	Type	Description
`project`	`string`	Project slug to scope the graph. Omit for org-wide view.

Response shape:

{
  "nodes": [
    {
      "sessionId": "abc123…",
      "agentId": "agent_dev_01",
      "agentName": "Dev Agent",
      "agentRole": "worker",
      "status": "working",
      "health": "green",
      "costUsd": "0.42",
      "startedAt": "2026-06-02T14:00:00Z",
      "workType": "development",
      "issueIdentifier": "ENG-201",
      "issueTitle": "Add auth middleware",
      "workerId": "worker_abc",
      "projectName": "Rensei Platform",
      "toolCallCount": 37,
      "reservedFiles": ["/src/auth/index.ts"],
      "model": "claude-sonnet-4-6",
      "isSubAgent": false
    }
  ],
  "edges": [
    {
      "id": "handoff-0",
      "source": "abc123…",
      "target": "def456…",
      "type": "handoff"
    }
  ]
}

Sub-agent nodes include additional fields:

{
  "isSubAgent": true,
  "parentSessionId": "abc123…"
}

Operator Use Cases

Confirming an SDLC wave is running. Open the topology after triggering a Linear issue. You should see a research node appear, followed by a backlog-writer node, then one or more development nodes as the SDLC progresses.

Spotting fleet overload. A large number of working nodes with yellow health dots signals the fleet is under load. Check the daemon capacity view if you see queued sessions stacking up.

Investigating a handoff failure. If a research session completed but no development session appeared, look for a missing handoff edge. Check the work-item.handoff events in the factory events table or the Vercel runtime logs.

Verifying sub-agent delegation. Select a development node to see its reserved files. Sub-agent edges show whether parallel work is being dispatched correctly.

Session List - project-scoped list with health dots
Session Detail - single-session activity stream and diagnostics
Session Inspector - deep debug for a specific session
SDLC Default Template - the SDLC workflow that generates research → dev → qa topology patterns

Navigation