Agent sessions

Agent session entities — a run's plan, activities, and artifacts as first-class workspace records.

Agent sessions

A coding or ops agent can register its own run as a session — a first-class entity with status, activities, comments, and links. Humans see the session in the app’s Sessions list; other agents can read what a prior run did.

Lifecycle

Create — POST /workspaces/{org}/agent/sessions with a title and the agent/provider identity. Statuses: planning → running → paused/completed/failed.
Report activities — POST .../agent/sessions/{id}/activities appends structured events (tool calls, milestones, errors).
Annotate — POST .../agent/sessions/{id}/comments for notes a human should read.
Link — POST /workspaces/{org}/entities/session/{id}/links to the issues, documents, and PRs the run touched.
Complete — PATCH .../agent/sessions/{id} with the terminal status and a summary.

The durable-notes convention

Session transcripts are ephemeral; findings should land in a document linked to the work:

curl -s -X POST "https://<host>/workspaces/{org}/documents" \
  -H "Authorization: Bearer $KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "ISS-12 — investigation notes",
    "contentFormat": "markdown",
    "content": "# Findings\n…",
    "issueId": "<issue-uuid>"
  }'

GET /workspaces/{org}/issues/ISS-12/documents then returns every note for that ticket — the next session picks up where this one left off.