Agent sessions

A run is cheap and durable. Open one per user conversation and keep appending; do not open one per question.

curl -X POST "https://runlogai.com/runlogapi/api/agent-runs" \
  -H "Authorization: Bearer $RUNLOG_API_KEY" \
  -H "X-Project-Id: p7Kd2mQx" \
  -H "Content-Type: application/json" \
  -d '{
  "projectId": "p7Kd2mQx",
  "title": "Why does checkout retry?",
  "tool": "atlas"
}'

{
  "createdAt": "2026-08-07T18:30:00Z",
  "projectId": "p7Kd2mQx",
  "runId": "run_9Fb3TnQ2",
  "status": "open",
  "title": "Why does checkout retry?"
}

The answer is grounded: `source` parts carry the cell ids the claim rested on, so you can render a citation the user can click through to a file and line rather than a confidence score.

The route returns the message you sent as soon as it lands and never waits on the answer: Ro's reply lands on the run, so open the run's stream (mint a stream ticket first) or read the run until an assistant message follows yours.

Every message carries `metadata.createdAt` — when it was written, as an ISO-8601 UTC instant with milliseconds. It is what orders a thread and what measures how long a turn took.

curl -X POST "https://runlogai.com/runlogapi/api/agent-runs/run_9Fb3TnQ2/messages" \
  -H "Authorization: Bearer $RUNLOG_API_KEY" \
  -H "X-Project-Id: p7Kd2mQx" \
  -H "Content-Type: application/json" \
  -d '{
  "text": "Why does the checkout client retry on a declined card?"
}'

{
  "userMessage": {
    "id": "m_1",
    "metadata": {
      "createdAt": "2026-02-11T09:14:22.418Z"
    },
    "parts": [
      {
        "text": "Why does the checkout client retry on a declined card?",
        "type": "text"
      }
    ],
    "role": "user"
  }
}

A normal keyed call. The ticket opens the stream once, within 120 seconds, so the key itself never travels in a URL. Mint one per connection.

curl -X POST "https://runlogai.com/runlogapi/api/agent-runs/run_9Fb3TnQ2/stream-ticket" \
  -H "Authorization: Bearer $RUNLOG_API_KEY" \
  -H "X-Project-Id: p7Kd2mQx"

{
  "expiresInSeconds": 120,
  "ticket": "st_7Qk2Mv…"
}

Two credentials open it: the API key as a bearer header, or a stream ticket on the query string for a client that cannot set a header (EventSource). The ticket comes from POST /v1/api/agent-runs/{runId}/stream-ticket, opens the stream once within 120 seconds, and the stream then lives as long as the connection.

The stream speaks the AI SDK UI message-stream protocol — `data:`-only SSE frames with a `type` discriminator — announced by the `x-vercel-ai-ui-message-stream: v1` response header. Any client built against that protocol consumes it unchanged.

Every part event carries the stable id `messageId:partIdx`, so a late-arriving part places itself correctly regardless of arrival order.

Reconnecting replays every finished turn from persistence before any new delta, so a dropped connection never loses an answer.

# 1. Mint a ticket: a normal keyed call. It opens the stream once, within two minutes.
curl -X POST "https://runlogai.com/runlogapi/api/agent-runs/run_9Fb3TnQ2/stream-ticket" \
  -H "Authorization: Bearer $RUNLOG_API_KEY" \
  -H "X-Project-Id: p7Kd2mQx"
# → {"ticket": "st_7Qk2Mv…", "expiresInSeconds": 120}

# 2. Open the stream with it. No header, so EventSource can; it lives as long as the connection.
curl -N "https://runlogai.com/runlogapi/api/agent-runs/run_9Fb3TnQ2/stream?ticket=$TICKET"

curl -X GET "https://runlogai.com/runlogapi/api/agent-runs/run_9Fb3TnQ2/stream" \
  -H "Authorization: Bearer $RUNLOG_API_KEY" \
  -H "X-Project-Id: p7Kd2mQx"

data: {"type":"text-delta","id":"m_2:0","delta":"It retries once against"}

This is the same message route as a question, and it answers once your message has landed: the turn runs on the worker, and its reply, its plan of record and its writes arrive on the run's stream.

A change the ask plainly wants starts as the reply lands, and the reply says so. One that rests on a guess about what you meant, or that the consequence floor holds, is staged onto the run's `pendingWrites` — show it to the user, then confirm or decline each one by id.

curl -X POST "https://runlogai.com/runlogapi/agent-runs/run_9Fb3TnQ2/messages" \
  -H "Authorization: Bearer $RUNLOG_SESSION_TOKEN" \
  -H "X-Project-Id: p7Kd2mQx" \
  -H "Content-Type: application/json" \
  -d '{
  "text": "Add exponential backoff to Router.send and update its callers."
}'

{
  "userMessage": {
    "id": "m_3",
    "parts": [
      {
        "text": "Add exponential backoff to Router.send and update its callers.",
        "type": "text"
      }
    ],
    "role": "user"
  }
}

The plan is persisted, not discarded — it names the changes it would make and the terms it read without changing, each citing what it rests on. A plan you did not approve is still readable later.

curl -X GET "https://runlogai.com/runlogapi/agent-runs/run_9Fb3TnQ2" \
  -H "Authorization: Bearer $RUNLOG_SESSION_TOKEN" \
  -H "X-Project-Id: p7Kd2mQx"

{
  "pendingWrites": [
    {
      "id": "pw_3Rt7Yu",
      "kind": "cell_edit",
      "summary": "Router.send — wrap the request in a backoff loop capped at 3 attempts"
    },
    {
      "id": "pw_8Kq1Za",
      "kind": "source_transition",
      "summary": "Promote Artifacts/design/retry-note.md to source"
    }
  ],
  "run": {
    "projectId": "p7Kd2mQx",
    "runId": "run_9Fb3TnQ2"
  }
}