Runs

A Run is a single task execution against a session. Events stream in real time over SSE.

What is a Run?

A Run is a single task submitted to an agent. Each run:

1. Targets a named Profile (the agent’s definition)
2. Carries a SubTask (the work to do)
3. Produces a stream of RunEvents (progress, tool calls, responses)
4. Is assigned a unique runId and a sessionId

Multiple runs can share a session, but only one run executes per session at a time.

---

Submitting a Run

POST /api/runs
Content-Type: application/json

{
  "profile": "researcher",
  "title": "Q1 market analysis",
  "prompt": "Summarize the top AI agent frameworks released in Q1 2026.",
  "files": []
}

Response 202 Accepted:

{
  "runId": "run-f3a9b72c",
  "sessionId": "sess-a1b2c3d4-e5f6g7h8"
}

---

SubTask Schema

type SubTask struct {
  ID        string
  ParentID  string
  Profile   string
  SessionID string
  Title     string
  Prompt    string
  Files     []string
}

---

Streaming Events (SSE)

Once you have a runId, open an SSE stream:

curl -N https://api.orcapods.ai/api/runs/run-f3a9b72c/stream \
  -H 'Accept: text/event-stream'

The conductor streams RunEvent objects as Server-Sent Events. Events are replayed for late subscribers (the conductor buffers the run’s event log).

---

RunEvent Types

Every event in the stream is a JSON object with a type field:

progress

Lifecycle milestones emitted by the runner and conductor.

{
  "type": "progress",
  "message": "Starting run...",
  "ts": "2026-04-25T10:00:00Z"
}

session_init

Runtime-native conversation handle emitted once per run when the sidecar reports it. The conductor preserves it as runtimeSessionId; UIs can ignore this event unless they need to correlate an Orca session with a Claude SDK session_id or Codex thread_id.

{
  "type": "session_init",
  "runtimeSessionId": "sdk-session-or-thread-id",
  "ts": "2026-04-25T10:00:01Z"
}

assistant

A text response from the LLM.

{
  "type": "assistant",
  "message": "Based on my research, the top frameworks are...",
  "ts": "2026-04-25T10:00:02Z"
}

tool_call

The agent is invoking a tool.

{
  "type": "tool_call",
  "toolCallId": "call_abc123",
  "toolName": "web_search",
  "input": { "query": "AI agent frameworks 2026", "max_results": 5 },
  "ts": "2026-04-25T10:00:03Z"
}

tool_result

The result of a tool invocation.

{
  "type": "tool_result",
  "toolCallId": "call_abc123",
  "toolName": "web_search",
  "output": { "results": [...] },
  "isError": false,
  "ts": "2026-04-25T10:00:04Z"
}

usage

Token usage reported by the LLM provider.

{
  "type": "usage",
  "usage": {
    "inputTokens": 1240,
    "outputTokens": 380,
    "cacheReadTokens": 800,
    "cacheCreateTokens": 440
  },
  "ts": "2026-04-25T10:00:10Z"
}

result

The final answer produced by the agent. Signals that the run is complete.

{
  "type": "result",
  "message": "1. LangGraph 2.0\n2. Orca\n3. AutoGen v3",
  "ts": "2026-04-25T10:00:11Z"
}

error

An unrecoverable error during the run.

{
  "type": "error",
  "message": "LLM provider returned 429: rate limit exceeded",
  "ts": "2026-04-25T10:00:05Z"
}

---

Complete Event Sequence

A typical run produces events in this order:

progress    "Starting run..."
progress    "Session ready"
assistant   (first token stream begins)
tool_call   web_search { query: "..." }
tool_result web_search { results: [...] }
assistant   (continues writing)
tool_call   web_extract { urls: [...] }
tool_result web_extract { content: "..." }
assistant   (final answer)
result      "Final answer: ..."
usage       { inputTokens: 1240, outputTokens: 380 }

---

Consuming Events in TypeScript

const BASE = "https://api.orcapods.ai";
const apiKey = process.env.ORCA_API_KEY ?? "ao_..."; // Tenant API key (Settings → API Keys)
const authHeaders = {
  Authorization: `Bearer ${apiKey}`,
};

type RunEvent = { type: string; message?: string };

function parseSSEBlock(block: string): RunEvent | undefined {
  const data = block
    .split("\n")
    .filter((line) => line.startsWith("data:"))
    .map((line) => line.slice(5).trimStart())
    .join("\n");
  return data ? JSON.parse(data) : undefined;
}

async function* streamSSE(response: Response): AsyncGenerator<RunEvent> {
  if (!response.ok || !response.body) throw new Error("stream failed");

  const reader = response.body.getReader();
  const decoder = new TextDecoder();
  let buffer = "";

  while (true) {
    const { done, value } = await reader.read();
    if (done) break;
    buffer += decoder.decode(value, { stream: true });

    let boundary;
    while ((boundary = buffer.indexOf("\n\n")) !== -1) {
      const event = parseSSEBlock(buffer.slice(0, boundary));
      buffer = buffer.slice(boundary + 2);
      if (event) yield event;
    }
  }

  buffer += decoder.decode();
  if (buffer.trim()) {
    const event = parseSSEBlock(buffer);
    if (event) yield event;
  }
}

async function runAgent(profileName: string, prompt: string) {
  // 1. Submit run
  const { runId } = await fetch(`${BASE}/api/runs`, {
    method: "POST",
    headers: { "Content-Type": "application/json", ...authHeaders },
    body: JSON.stringify({
      profile: profileName,
      title: "Task",
      prompt,
    }),
  }).then((r) => r.json());

  // 2. Stream events. Use fetch instead of EventSource when you need headers.
  const response = await fetch(`${BASE}/api/runs/${runId}/stream`, {
    headers: { Accept: "text/event-stream", ...authHeaders },
  });

  for await (const event of streamSSE(response)) {
    switch (event.type) {
      case "assistant":
        process.stdout.write(event.message ?? "");
        break;
      case "result":
        return event.message ?? "";
      case "error":
        throw new Error(event.message);
    }
  }

  return "";
}

const result = await runAgent("researcher", "What is LangGraph?");
console.log("\n\nFinal:", result);

---

Run Persistence

Runs are stored in an append-only JSONL log when AGENT_ORC_RUNS_DIR is set on the conductor:

AGENT_ORC_RUNS_DIR=/data/runs ./conductor

Each run gets one <runId>.jsonl file containing a header, event lines, and a finish line. Conductor replays these files on restart to reconstruct the in-memory run registry.

Without AGENT_ORC_RUNS_DIR, runs are in-memory only and lost on conductor restart.

---

Listing & Inspecting Runs

# List recent runs
curl https://api.orcapods.ai/api/runs

# Get a specific run
curl https://api.orcapods.ai/api/runs/run-f3a9b72c

The GET /api/runs/{id} response includes the full event log for completed runs.

---

Run Status

Status	Description
running	Actively executing on a session
ok	result event received
error	error event received
cancelled	Explicitly cancelled
interrupted	Orphaned by conductor restart and closed by the boot reconciliation sweep

Stopping a Run

Use DELETE /api/runs/{runId} for normal, cooperative cancellation. It cancels the run context, aborts the runner stream and sidecar turn, and returns 204 No Content.

If the run remains stuck, use POST /api/runs/{runId}/terminate as a last resort. Termination independently attempts to cancel any in-process run, waits up to two seconds for the session’s run claim to drain normally, then steals the claim only if it remains held. It also marks the durable run row as cancelled; a late completion cannot overwrite that status. The response reports which steps succeeded:

{
  "runId": "run-f3a9b72c",
  "cancelled": true,
  "sessionReleased": true,
  "claimStolen": false,
  "statusWritten": true,
  "sessionId": "sess-a1b2c3d4-e5f6g7h8",
  "warnings": []
}

Termination is idempotent and still attempts the durable status and session-release steps when the run is no longer in the current conductor’s in-memory registry. claimStolen: true identifies a claim that did not drain and had to be forcibly taken. Any warnings are stable codes rather than internal error details.