Agent Workspace Stream API
Agent Workspace Stream API
GET /api/agent-workspace/stream
Fleet-wide Server-Sent Events (SSE) stream delivering real-time pipeline state and agent log output for all accessible products.
Authentication
Requires a valid session cookie. Returns 401 Unauthorized if not authenticated.
Response
Content-Type: text/event-stream
The connection stays open indefinitely. The server pushes events as they occur.
Events
fleet_snapshot
Emitted once on initial connection. Contains the full current state of all active pipeline runs (up to 50) plus the 300 most-recent log lines.
event: fleet_snapshot
data: [<PipelineSnapshot>, ...]
Emits an empty array ([]) if there are no active runs.
fleet_update
Emitted during polling (every 3 seconds) when one or more pipelines have changed state. Only pipelines whose fingerprint has changed are included.
event: fleet_update
data: [<PipelineSnapshot>, ...]
A fingerprint covers: status, per-job status values, and the count of pending interventions. No event is emitted when nothing has changed.
fleet_logs
Emitted when new agent log entries are available for any active run.
event: fleet_logs
data: [<AgentLog>, ...]
Up to 50 new log entries are included per poll cycle per pipeline.
heartbeat
Emitted every 15 seconds to keep the connection alive through proxies and load balancers.
event: heartbeat
data: {"ts": 1718000000000}
error
Emitted when the server fails to load the initial state.
event: error
data: {"message": "Failed to load initial state"}
Data Types
PipelineSnapshot
| Field | Type | Description |
|---|---|---|
id | string | Pipeline run ID |
projectId | string | Associated project ID |
projectName | string | Human-readable project name |
status | string | null | Current pipeline status |
startedAt | string | null | ISO timestamp of run start |
trigger | string | What triggered the run |
triggerData | unknown | Trigger payload |
jobs | SlimJob[] | Agent jobs in this run |
pendingInterventions | SlimIntervention[] | Unresolved human interventions |
SlimJob
| Field | Type | Description |
|---|---|---|
id | string | Job ID |
pipelineRunId | string | Parent run ID |
agentType | string | Type of agent (e.g. implementing) |
status | string | null | Job status |
startedAt | Date | null | Job start time |
completedAt | Date | null | Job completion time |
error | string | null | Error message if failed |
SlimIntervention
| Field | Type | Description |
|---|---|---|
id | string | Intervention ID |
pipelineRunId | string | Target pipeline run |
type | string | One of: interrupt, inject, take_over, resume, note |
message | string | null | Optional instruction or note text |
status | string | pending or resolved |
createdAt | Date | Creation timestamp |
Active Pipeline Statuses
The stream only includes runs whose status is one of:
queued, researching, architecting, designing, implementing, testing, awaiting_approval, releasing, marketing, documenting, syncing_branches
Completed or failed runs are excluded.
Runtime Notes
- Runtime: Node.js (
runtime = "nodejs") - Max duration: 300 seconds (per serverless function invocation limit)
- Poll interval: 3 000 ms
- Heartbeat interval: 15 000 ms (every 5th poll tick)
- Recommended headers for proxies: The response includes
X-Accel-Buffering: noto disable Nginx buffering.