Sessions and runs

The SR&ED workspace is built on top of projects, sessions, persisted message history, and explicit run execution.

Endpoint map

Endpoint	Purpose
POST /api/v1/projects	Create a project
GET /api/v1/projects	List current user projects
GET /api/v1/projects/{projectId}	Fetch one project
PATCH /api/v1/projects/{projectId}	Update project fields such as name, description, or status
DELETE /api/v1/projects/{projectId}	Delete a project
POST /api/v1/projects/{projectId}/sessions	Create a session
GET /api/v1/projects/{projectId}/sessions	List sessions in a project
GET /api/v1/projects/{projectId}/sessions/{sessionId}	Fetch one session
PATCH /api/v1/projects/{projectId}/sessions/{sessionId}/status	Update session status
PATCH /api/v1/projects/{projectId}/sessions/{sessionId}/title	Rename a session
DELETE /api/v1/projects/{projectId}/sessions/{sessionId}	Delete a session
GET /api/v1/sessions/{sessionId}/history	Fetch chronological session history
POST /api/v1/sessions/{sessionId}/runs	Execute an AI run for a session

Typical flow

1. Create or select a project
2. Create a session for that project
3. Upload and wait for files to become READY if file context is needed
4. Submit a run for the session
5. Read the latest assistant output from the returned message IDs or reload history

Project creation and updates

Project creation accepts:

{
  "name": "Project name",
  "fiscalYear": "2025",
  "description": "Optional description"
}

Project patch requests are partial and can update:

• name
• fiscalYear
• description
• status

Session creation

Session creation accepts:

{
  "type": "PRECHECK",
  "title": "Optional title"
}

The backend session types are currently:

• PRECHECK
• T661
• T661_GEN
• T661_DRAFT
• T661_ANALYSIS
• LOGBOOK

The frontend may present broader UI types and map them into the supported run set before calling the backend.

History retrieval

History is available at:

• GET /api/v1/sessions/{sessionId}/history?limit=50

Important behavior:

• the backend clamps limit into 0..200
• messages are returned in chronological order
• only USER and ASSISTANT messages are included in the returned DTO

Run request

Run execution accepts a request with these fields:

{
  "type": "T661",
  "input": "User prompt or guided intake output",
  "selected_file_ids": ["uuid-1", "uuid-2"],
  "history_limit": 10
}

Important behavior:

• type and input are required
• history_limit defaults to 10
• history_limit is clamped to 0..50
• file attachment is strict: if selected_file_ids is empty or omitted, no files are attached implicitly
• every selected file must belong to the project and be in READY index state

What happens during a run

AgentRunService currently does this:

1. verifies session ownership
2. reserves AI-run quota
3. loads bounded session history
4. validates selected files
5. persists the new user message
6. attaches signed R2 download URLs for selected files
7. attaches project-scoped GitHub runtime access when available
8. sends the task envelope to the Python worker
9. persists the assistant result as a message
10. confirms or cancels quota reservation

If the Python call fails, the backend returns a structured failed result and rolls the quota reservation back.

Run response

The run response contains:

Field	Meaning
runId	Backend-generated run UUID
python	Raw Python worker result payload
messages.userMessageId	Persisted user message UUID
messages.assistantMessageId	Persisted assistant message UUID
selectedFileIds	File IDs attached to the run

Use the history endpoint or the stored message IDs to reconcile chat state after a run.