# BRA403: Execution API: Workflow Execution & Telemetry
    https://www.telosbrain.com/skills/BRA403?v=5
    How to list a brain's workflows (with pending inbox-task counts), run them synchronously (SSE streaming) or asynchronously (fire-and-forget with callback), pass optional run variables for {{input.*}} template tags and pre-called input-tools (BRA409), hold a multi-turn chat session against a single run, stop an in-flight turn without closing the session (POST /runs/{id}/stop), and retrieve run telemetry and unit-of-work telemetry via the Execution API — including model, thinking mode and turn totals on run telemetry. Documents when a run settles Failed (max-turns exhausted, final max_tokens with no retries). Also notes when a Completed, Failed, or AwaitingInput run becomes eligible for learning evals (BRA207). Documents SSRF rules for async callbackUrl (allowed-callback-domains).
    
    ## Instructions
    See BRA401 for authentication and conventions. See BRA402 for entity and unit-of-work setup.
    
    ---
    
    ## List workflows
    
    ### `GET /workflows`
    
    Returns every workflow in the brain, ordered by name, with a count of linked inbox tasks that are still pending (status is not `COMPLETED` or `CANCELLED`).
    
    Response `200 OK`:
    
    ```json
    [
      {
        "name": "Chat",
        "code": "WF-CHAT",
        "version": 2,
        "description": "Open chat session",
        "pendingTasks": 3
      }
    ]
    ```
    
    | Field | Notes |
    |---|---|
    | `name` | Workflow display title |
    | `code` | Stable deploy key used to run the workflow |
    | `version` | Integer schema version |
    | `description` | Optional |
    | `pendingTasks` | Linked inbox tasks not `COMPLETED` or `CANCELLED` (`PENDING`, `AWAITING_APPROVAL`, `RUNNING`, `FAILED`) |
    
    ---
    
    ## Workflow Execution
    
    Workflows are addressed by **code** and resolved to the active workflow within the brain's scope. Both run endpoints share the same execution engine and the same request body.
    
    ### Shared request body
    
    All fields are optional:
    
    ```json
    {
      "inputMessage": "Draft a proposal",
      "entityId": "3f0c...",
      "unitOfWorkId": "7b2d...",
      "variables": {
        "widget_reference": "WID-001",
        "current_date": "2026-07-30"
      },
      "callbackUrl": "https://app.example.com/brain/callbacks/run-complete",
      "caller_jwt": "eyJhbGc..."
    }
    ```
    
    | Field | Notes |
    |---|---|
    | `inputMessage` | The triggering user message. |
    | `entityId` | Optional runtime scope. |
    | `unitOfWorkId` | Optional runtime scope for template tags (e.g. `{{#unitOfWork.context}}`). Nothing is hard-coded into the prompt; workflows that need the logs declare those tags in Instructions. |
    | `variables` | Optional string→string map persisted on the `WorkflowRun` and exposed to templates as `{{input.<key>}}`. Omit or leave null for unchanged behaviour. Keys and values are plain strings (no type coercion). See [Run variables](#run-variables-input) and **BRA409**. |
    | `callbackUrl` | Honoured on the async path only. Must be `https` (or `http://localhost` / `http://127.0.0.1` in Development). Subject to the brain's shared outbound host allowlist — see [Async callback SSRF rules](#async-callback-ssrf-rules). |
    | `caller_jwt` | Optional opaque JWT forwarded as `Authorization: Bearer` on outbound calls for connectors with `auth-type: caller-jwt` (BRA274). Encrypted at rest on the `WorkflowRun`. Never logged or echoed. Nested `run_workflow` / workflow-tool child runs inherit it. Brain does not validate the token. Clerk JWTs often expire in ~60 seconds — on `/run/async`, tool dispatch may happen after expiry and the downstream API will 401. |
    
    ### Run variables (`variables` → `{{input.*}}`)
    
    Pass caller-defined named strings into a workflow at invocation time. Both sync
    and async endpoints accept the same optional `variables` object.
    
    **What happens**
    
    1. The map is persisted on the `WorkflowRun` as JSON before execution starts
       (so Hangfire async jobs can read it from the database).
    2. Template tags `{{input.<key>}}` resolve to those values in workflow
       Instructions, system prompts, tool response markdown, and `input-tools`
       parameter mappings (see **BRA201** §8.0a / **BRA409**).
    3. Nested `run_workflow` / workflow-tool child runs inherit the parent's
       variables automatically.
    4. Missing keys render blank (never an error). Omitting `variables` leaves
       `WorkflowRun.Variables` null — fully backward-compatible.
    
    **Example — sync with variables**
    
    ```http
    POST /workflows/WF-INPUT-VARIABLES/run/sync
    Authorization: Bearer {brainApiKey}
    Content-Type: application/json
    
    {
      "inputMessage": "Produce the briefing.",
      "variables": {
        "topic": "Telos Brain Execution API",
        "seed_question": "What is the Execution API used for in one sentence?"
      }
    }
    ```
    
    **Example — async with variables**
    
    ```http
    POST /workflows/WF-WIDGET/run/async
    Authorization: Bearer {brainApiKey}
    Content-Type: application/json
    
    {
      "variables": {
        "widget_reference": "WID-001"
      },
      "callbackUrl": "https://app.example.com/brain/callbacks/run-complete"
    }
    ```
    
    Wire the same keys in the workflow schema:
    
    - Instructions: `Working on {{input.topic}}.`
    - Pre-called tools (`input-tools`):
    
      ```yaml
      input-tools:
        - variable: widget_information
          tool: get_widget_details
          parameters:
            widget_reference: "{{input.widget_reference}}"
      ```
    
    Full authoring guide: **BRA409**. Template taxonomy: **BRA204** §3.6.
    
    ### `POST /workflows/{code}/run/sync` — synchronous (SSE)
    
    Streams the result in real time as **Server-Sent Events**. The run is created at status `Running` (never `Queued`). Live progress events (`status`, `thinking`, `tool_call`, `tool_result`, and on Claude `text`) are emitted while the loop works. On non-streaming providers the final reply is still chunked as `text` deltas after the loop.
    
    Rather than terminating, a successful sync run is **left open** as a chat session at status `AwaitingInput`, so you can continue the same conversation turn by turn (see [Chat Sessions](#chat-sessions)). It transitions to `Failed` on error or client disconnect. The stream begins with a `run_started` event carrying the run id you continue or close the session with.
    
    Response headers:
    
    ```
    Content-Type: text/event-stream
    Cache-Control: no-cache
    Connection: keep-alive
    ```
    
    Event stream:
    
    ```
    data: {"type": "run_started", "runId": "44291..."}
    data: {"type": "status", "phase": "model"}
    data: {"type": "thinking", "delta": "I should look up the customer first."}
    data: {"type": "tool_call", "name": "crm_lookup", "id": "toolu_01...", "input": {"customerId": "42"}}
    data: {"type": "tool_result", "name": "crm_lookup", "id": "toolu_01...", "ok": true, "output": {"name": "Acme"}}
    data: {"delta": "We", "type": "text"}
    data: {"delta": " currently", "type": "text"}
    data: {"delta": " have...", "type": "text"}
    data: {"type": "done"}
    ```
    
    Progress events are emitted **while the turn is running** so a harness chat UI can show steps (model wait, thinking, tool calls) instead of a silent wait. Unknown event types should be ignored so older clients stay compatible.
    
    | `type` | When | Fields |
    |---|---|---|
    | `run_started` | Immediately, before work begins | `runId` |
    | `status` | Each time the model is about to be called | `phase` (`model`) |
    | `thinking` | While the provider is generating reasoning | `delta` (token-level on Claude streaming; one blob on non-streaming providers) |
    | `tool_call` | Immediately before a tool is dispatched | `name`, `id`, `input` (JSON object when the arguments are JSON, otherwise a string) |
    | `tool_result` | After that tool returns | `name`, `id`, `ok`, `output` (JSON object when the result is JSON, otherwise a string) |
    | `text` | While the provider is writing the reply (Claude streaming), or after the loop if the call was non-streaming | `delta` |
    | `error` | Terminal failure | `message` |
    | `done` | Always last | — |
    
    On Claude, `thinking` and `text` deltas are the provider's own tokens as they are generated. `tool_call` / `tool_result` still fire around tool dispatch. Non-streaming providers keep the previous behaviour (thinking as one blob after the call; reply text chunked at the end).
    
    On failure, a terminal error event precedes `done`:
    
    ```
    data: {"type": "error", "message": "Workflow 'foo' was not found."}
    data: {"type": "done"}
    ```
    
    > **Note:** because SSE commits a `200` response and headers before the first token, an unknown workflow code on the sync path surfaces as a terminal `error` event rather than a `404`. Use the async path if you need a hard `404` for an unresolved code.
    
    ### `POST /workflows/{code}/run/async` — asynchronous (fire-and-forget)
    
    Creates the run at status `Queued`, enqueues a background job, and returns immediately.
    
    Response `202 Accepted`:
    
    ```json
    {
      "runId": "44291...",
      "status": "queued"
    }
    ```
    
    Returns `404 Not Found` if the workflow code does not resolve within the brain.
    
    The engine executes the run in the background (`Queued → Running → Completed / Failed`). A run settles `Failed` (not `Completed`) when the model hits a terminal limit — the workflow's `max-turns` cap is exhausted, or the final `output-tokens` attempt stops with `max_tokens` and no further retry remains — as well as on transport / API errors and cancellation. If a `callbackUrl` was supplied, a webhook is POSTed on completion:
    
    ```http
    POST https://app.example.com/brain/callbacks/run-complete
    Content-Type: application/json
    
    {
      "runId": "44291...",
      "status": "complete"
    }
    ```
    
    `status` is `complete` or `failed`. Webhook delivery is retried on transient failure; a persistent failure is logged but does not fail the run. Results are always retrievable via telemetry.
    
    #### Async callback SSRF rules
    
    Outbound `callbackUrl` delivery is SSRF-hardened (same rules as declared-tool
    `api.path` webhooks — see BRA201 §4.3):
    
    | Rule | Behaviour |
    |---|---|
    | Scheme | `https` required. In Development only, `http://localhost` and `http://127.0.0.1` (any port) are also allowed. |
    | Host allowlist | Optional per-brain list from `brain-compose.yml` `allowed-callback-domains`. When set, the callback host must match an entry exactly (case-insensitive; no wildcards). When omitted, any public host is allowed. |
    | IP blocklist | Always applied after DNS resolution: private, loopback, link-local, and cloud metadata ranges (e.g. `169.254.169.254`) are blocked in all environments. |
    | Redirects | Automatic redirect following is disabled on the callback HTTP client. |
    | Rejection | An unsafe `callbackUrl` marks the run `Failed` and no outbound POST is made. A `SYSTEM_CHANGE` inbox entry (`PROCESSED`) is created with the denied URL, reason, workflow code, and run id. |
    
    Configure harness callback hosts in `brain-compose.yml` before using async runs:
    
    ```yaml
    allowed-callback-domains:
      - app.example.com
    ```
    
    ---
    
    ## Chat Sessions
    
    A synchronous run is a **chat session**: it is the *same* run for the whole conversation. Each turn appends to that run's message history, and the engine replays the run's own transcript as context on every subsequent turn — so the assistant remembers the conversation without you resending it. There is no separate session id: the **run id** (from the `run_started` event) *is* the session.
    
    **Lifecycle.** A session moves through:
    
    ```
    Running  →  AwaitingInput  ⇄  Running (next turn)  →  Completed
                        │
                        └──────────→  Completed (explicit close, or inactivity timeout)
    ```
    
    After each successful turn the run settles at `AwaitingInput` (open) with an `expiresDateUtc`. It is closed to `Completed` when you call `complete`, or automatically when its inactivity timeout passes (see [Session timeout](#session-timeout)). Manual **Run eval** can target a `Completed`, `Failed`, or `AwaitingInput` run (BRA207). Automatic evals still fire on `Completed`.
    
    **Cost and billing.** Each turn (including a sync call that leaves the run `AwaitingInput`) recalculates the run's LLM `CostCents` from its messages. OpenRouter turns that stored provider-billed `usage.cost` on every token-bearing message use that sum; otherwise cost is tokens × date-effective `LlmPrices` for the run's model (`openrouter` + catalogue id for OpenRouter). Daily time-based charges include open sessions: the night job bills `RunSeconds - BilledSeconds` and then raises `BilledSeconds`, so a chat that stays open is charged that day and a later continuation only bills the unbilled remainder.
    
    ### `POST /runs/{runId}/messages` — continue a session
    
    Posts the next user message to an open session and streams the turn as SSE, in the identical wire format to `/workflows/{code}/run/sync` (including a leading `run_started`). The run reuses its own entity / unit-of-work scope; the only per-turn input is the message.
    
    ```json
    {
      "inputMessage": "And what about next quarter?"
    }
    ```
    
    Validated before the stream commits, so these are real HTTP statuses:
    
    | Status | When |
    |---|---|
    | `200` (stream) | The session is open (`AwaitingInput`) and the turn is streaming. |
    | `404 Not Found` | No run with that id belongs to the brain. |
    | `409 Conflict` | The run has a turn in progress, or is `Completed` / `Failed` and can no longer be continued. |
    
    A turn started here re-arms the session's `expiresDateUtc` from the moment it finishes, so an actively used session never times out.
    
    ### `POST /runs/{runId}/stop` — stop an in-flight turn
    
    Stops the current turn if it is `Queued` or `Running` and leaves the session **open** (`AwaitingInput`) so you can send another message. This is not the same as `complete`: the run is not closed and is not evaluated automatically.
    
    Response `200 OK`:
    
    ```json
    {
      "runId": "44291...",
      "status": "AwaitingInput"
    }
    ```
    
    | Status | When |
    |---|---|
    | `200 OK` | The turn was stopped, or the run had already settled (idempotent). |
    | `404 Not Found` | No run with that id belongs to the brain. |
    
    Stopping aborts the in-flight turn, including any model request that is still in progress. Any assistant text already written stays on the run. The session timeout is re-armed from the moment of the stop. A connected SSE stream ends once the turn leaves `Queued` / `Running`.
    
    A client disconnect on `/run/sync` or `/messages` (idle timeout, closed socket) still **fails** the run. If a turn may run longer than the connection can stay open, use `/run/async` instead of relying on a dropped sync stream.
    
    To close the session after stopping, call `POST /runs/{runId}/complete`.
    
    ### `POST /runs/{runId}/complete` — close a session
    
    Closes an open session, transitioning it to `Completed` so it becomes eligible for
    learning evaluation (BRA207 / BRA091). If the brain has a `workflowrun:complete`
    workflow with `trigger-mode: automatic`, an eval is enqueued. If only
    `trigger-mode: manual` (or omitted) is configured, use the admin UI **Run eval**
    button on the run detail page (or `POST /brains/{instance}/runs/{runId}/eval` on
    the Management API).
    
    Response `200 OK`:
    
    ```json
    {
      "runId": "44291...",
      "status": "Completed"
    }
    ```
    
    Idempotent: closing an already-`Completed` session also returns `200`. Returns `404 Not Found` when no such run belongs to the brain, and `409 Conflict` when the run cannot be closed in its current state (e.g. a turn is still in progress — call `stop` first if you need to close immediately).
    
    ### Session timeout
    
    An open session that is neither continued nor closed is swept to `Completed` once its `expiresDateUtc` passes, so abandoned chats do not linger. The inactivity window is set per workflow via the `session-timeout` frontmatter field (in minutes; see BRA201); when a workflow declares none, the engine default of **30 minutes** applies. The window is measured from the end of the most recent turn and re-armed on every continuation.
    
    ---
    
    ## Telemetry
    
    ### `GET /runs/{id}/telemetry` — run telemetry (OTEL)
    
    Returns the full telemetry for a workflow run, projected to the [OpenTelemetry Semantic Conventions for Generative AI](https://opentelemetry.io/docs/specs/semconv/gen-ai/). Each persisted turn becomes a span; token usage maps to `gen_ai.usage.*` and tool calls to `gen_ai.tool.*`.
    
    Response `200 OK`:
    
    ```json
    {
      "runId": "44291...",
      "workflowId": "9c1a...",
      "entityId": "3f0c...",
      "unitOfWorkId": "7b2d...",
      "status": "Completed",
      "createdAt": "2026-07-09T07:10:00Z",
      "completedAt": "2026-07-09T07:10:04Z",
      "resource": {
        "gen_ai.system": "telos-brain",
        "gen_ai.request.model": "anthropic/claude-sonnet-4-6",
        "telos.thinking.mode": "effort"
      },
      "totals": {
        "gen_ai.usage.input_tokens": 1820,
        "gen_ai.usage.output_tokens": 430,
        "gen_ai.embeddings.count": 2,
        "telos.turns.used": 3,
        "telos.turns.max": 15
      },
      "spans": [...]
    }
    ```
    
    Resource / totals extensions (Telos-specific, alongside GenAI semantic conventions):
    
    | Attribute | Notes |
    |---|---|
    | `gen_ai.request.model` | Fully-qualified model the run executed against (`provider/model`) |
    | `gen_ai.embeddings.count` | Embeddings generated in the run (always present on `totals`). OTEL standardises `gen_ai.embeddings.dimension.count` (vector size) only; this is the count of embeddings produced. |
    | `telos.thinking.mode` | Workflow thinking mode (`none` \| `adaptive` \| `extended` \| `effort`) |
    | `telos.turns.used` | Completed assistant loop steps (excludes retries / `max_tokens` attempts) |
    | `telos.turns.max` | Effective max-turns cap for the run (workflow value or engine default 10) |
    
    Span attributes:
    
    | Attribute | Notes |
    |---|---|
    | `gen_ai.message.role` | `user` \| `assistant` \| `tool` |
    | `gen_ai.message.content` | Message content |
    | `gen_ai.usage.input_tokens` / `output_tokens` | Per-turn token counts |
    | `gen_ai.usage.cache_read_input_tokens` / `cache_creation_input_tokens` | Present only when the provider reports prompt-cache usage |
    | `gen_ai.tool.name` / `gen_ai.tool.call.id` | Present only on tool-call and tool-result turns |
    | `gen_ai.embeddings.count` | Embeddings generated for this turn (usually the assistant tool-call row). Omitted when unused. |
    | `gen_ai.response.finish_reason` | Provider stop reason on assistant turns (`end_turn` \| `tool_use` \| `max_tokens` \| ...) |
    | `gen_ai.request.max_tokens` | The output token cap the attempt ran with; doubles per output-token retry |
    | `error.message` | Present only on a failed / truncated assistant attempt |
    
    An output-token retry (see BRA201 `output-tokens`, the ordered per-attempt cap list) is not merged away: each attempt is its own assistant span carrying its `finish_reason` (`max_tokens` on a truncated attempt), the `max_tokens` cap it used and its consumed tokens, so a three-cap list that keeps truncating yields two truncated attempt spans before the final one. If that final attempt is still `max_tokens`, the run status is `Failed`.
    
    Returns `404 Not Found` if the run does not belong to the brain.
    
    ### `GET /units-of-work/{id}/telemetry` — unit-of-work telemetry
    
    Merges the unit of work's context and data logs into a single sequential stream.
    
    **Ordering:** by event `date`, then record type (Context before Data) for identical timestamps, then `createdAt`.
    
    Response `200 OK` — array of entries. Fields not applicable to a record type are `null`:
    
    ```json
    [
      {
        "recordType": "Context",
        "date": "2026-07-09T07:06:00Z",
        "source": "agent",
        "title": "Draft created",
        "message": "Initial draft generated from template",
        "type": null,
        "body": null,
        "createdAt": "2026-07-09T07:06:00Z"
      },
      {
        "recordType": "Data",
        "date": "2026-07-09T07:06:30Z",
        "source": "tool:crm_lookup",
        "title": null,
        "message": null,
        "type": "tool_response",
        "body": "{ ... }",
        "createdAt": "2026-07-09T07:06:30Z"
      }
    ]
    ```
    
    Returns `404 Not Found` if the unit of work does not belong to the brain.
    
    ---
    
    ## Endpoint Summary
    
    | Method | Path | Purpose | Success |
    |---|---|---|---|
    | `POST` | `/workflows/{code}/run/sync` | Run workflow, stream SSE, open a chat session | `200` (stream) |
    | `POST` | `/workflows/{code}/run/async` | Queue workflow run | `202` |
    | `POST` | `/runs/{id}/messages` | Continue an open chat session (stream SSE) | `200` (stream) |
    | `POST` | `/runs/{id}/stop` | Stop an in-flight turn and leave the session open | `200` |
    | `POST` | `/runs/{id}/complete` | Close an open chat session | `200` |
    | `GET` | `/runs/{id}/telemetry` | Run telemetry (OTEL GenAI) | `200` |
    | `GET` | `/units-of-work/{id}/telemetry` | Merged context/data telemetry | `200` |
    
    ← Skills Directory
    BRA403

    Execution API: Workflow Execution & Telemetry

    How to list a brain's workflows (with pending inbox-task counts), run them synchronously (SSE streaming) or asynchronously (fire-and-forget with callback), pass optional run variables for {{input.*}} template tags and pre-called input-tools (BRA409), hold a multi-turn chat session against a single run, stop an in-flight turn without closing the session (POST /runs/{id}/stop), and retrieve run telemetry and unit-of-work telemetry via the Execution API — including model, thinking mode and turn totals on run telemetry. Documents when a run settles Failed (max-turns exhausted, final max_tokens with no retries). Also notes when a Completed, Failed, or AwaitingInput run becomes eligible for learning evals (BRA207). Documents SSRF rules for async callbackUrl (allowed-callback-domains).

    See BRA401 for authentication and conventions. See BRA402 for entity and unit-of-work setup.
    
    ---
    
    ## List workflows
    
    ### `GET /workflows`
    
    Returns every workflow in the brain, ordered by name, with a count of linked inbox tasks that are still pending (status is not `COMPLETED` or `CANCELLED`).
    
    Response `200 OK`:
    
    ```json
    [
      {
        "name": "Chat",
        "code": "WF-CHAT",
        "version": 2,
        "description": "Open chat session",
        "pendingTasks": 3
      }
    ]
    ```
    
    | Field | Notes |
    |---|---|
    | `name` | Workflow display title |
    | `code` | Stable deploy key used to run the workflow |
    | `version` | Integer schema version |
    | `description` | Optional |
    | `pendingTasks` | Linked inbox tasks not `COMPLETED` or `CANCELLED` (`PENDING`, `AWAITING_APPROVAL`, `RUNNING`, `FAILED`) |
    
    ---
    
    ## Workflow Execution
    
    Workflows are addressed by **code** and resolved to the active workflow within the brain's scope. Both run endpoints share the same execution engine and the same request body.
    
    ### Shared request body
    
    All fields are optional:
    
    ```json
    {
      "inputMessage": "Draft a proposal",
      "entityId": "3f0c...",
      "unitOfWorkId": "7b2d...",
      "variables": {
        "widget_reference": "WID-001",
        "current_date": "2026-07-30"
      },
      "callbackUrl": "https://app.example.com/brain/callbacks/run-complete",
      "caller_jwt": "eyJhbGc..."
    }
    ```
    
    | Field | Notes |
    |---|---|
    | `inputMessage` | The triggering user message. |
    | `entityId` | Optional runtime scope. |
    | `unitOfWorkId` | Optional runtime scope for template tags (e.g. `{{#unitOfWork.context}}`). Nothing is hard-coded into the prompt; workflows that need the logs declare those tags in Instructions. |
    | `variables` | Optional string→string map persisted on the `WorkflowRun` and exposed to templates as `{{input.<key>}}`. Omit or leave null for unchanged behaviour. Keys and values are plain strings (no type coercion). See [Run variables](#run-variables-input) and **BRA409**. |
    | `callbackUrl` | Honoured on the async path only. Must be `https` (or `http://localhost` / `http://127.0.0.1` in Development). Subject to the brain's shared outbound host allowlist — see [Async callback SSRF rules](#async-callback-ssrf-rules). |
    | `caller_jwt` | Optional opaque JWT forwarded as `Authorization: Bearer` on outbound calls for connectors with `auth-type: caller-jwt` (BRA274). Encrypted at rest on the `WorkflowRun`. Never logged or echoed. Nested `run_workflow` / workflow-tool child runs inherit it. Brain does not validate the token. Clerk JWTs often expire in ~60 seconds — on `/run/async`, tool dispatch may happen after expiry and the downstream API will 401. |
    
    ### Run variables (`variables` → `{{input.*}}`)
    
    Pass caller-defined named strings into a workflow at invocation time. Both sync
    and async endpoints accept the same optional `variables` object.
    
    **What happens**
    
    1. The map is persisted on the `WorkflowRun` as JSON before execution starts
       (so Hangfire async jobs can read it from the database).
    2. Template tags `{{input.<key>}}` resolve to those values in workflow
       Instructions, system prompts, tool response markdown, and `input-tools`
       parameter mappings (see **BRA201** §8.0a / **BRA409**).
    3. Nested `run_workflow` / workflow-tool child runs inherit the parent's
       variables automatically.
    4. Missing keys render blank (never an error). Omitting `variables` leaves
       `WorkflowRun.Variables` null — fully backward-compatible.
    
    **Example — sync with variables**
    
    ```http
    POST /workflows/WF-INPUT-VARIABLES/run/sync
    Authorization: Bearer {brainApiKey}
    Content-Type: application/json
    
    {
      "inputMessage": "Produce the briefing.",
      "variables": {
        "topic": "Telos Brain Execution API",
        "seed_question": "What is the Execution API used for in one sentence?"
      }
    }
    ```
    
    **Example — async with variables**
    
    ```http
    POST /workflows/WF-WIDGET/run/async
    Authorization: Bearer {brainApiKey}
    Content-Type: application/json
    
    {
      "variables": {
        "widget_reference": "WID-001"
      },
      "callbackUrl": "https://app.example.com/brain/callbacks/run-complete"
    }
    ```
    
    Wire the same keys in the workflow schema:
    
    - Instructions: `Working on {{input.topic}}.`
    - Pre-called tools (`input-tools`):
    
      ```yaml
      input-tools:
        - variable: widget_information
          tool: get_widget_details
          parameters:
            widget_reference: "{{input.widget_reference}}"
      ```
    
    Full authoring guide: **BRA409**. Template taxonomy: **BRA204** §3.6.
    
    ### `POST /workflows/{code}/run/sync` — synchronous (SSE)
    
    Streams the result in real time as **Server-Sent Events**. The run is created at status `Running` (never `Queued`). Live progress events (`status`, `thinking`, `tool_call`, `tool_result`, and on Claude `text`) are emitted while the loop works. On non-streaming providers the final reply is still chunked as `text` deltas after the loop.
    
    Rather than terminating, a successful sync run is **left open** as a chat session at status `AwaitingInput`, so you can continue the same conversation turn by turn (see [Chat Sessions](#chat-sessions)). It transitions to `Failed` on error or client disconnect. The stream begins with a `run_started` event carrying the run id you continue or close the session with.
    
    Response headers:
    
    ```
    Content-Type: text/event-stream
    Cache-Control: no-cache
    Connection: keep-alive
    ```
    
    Event stream:
    
    ```
    data: {"type": "run_started", "runId": "44291..."}
    data: {"type": "status", "phase": "model"}
    data: {"type": "thinking", "delta": "I should look up the customer first."}
    data: {"type": "tool_call", "name": "crm_lookup", "id": "toolu_01...", "input": {"customerId": "42"}}
    data: {"type": "tool_result", "name": "crm_lookup", "id": "toolu_01...", "ok": true, "output": {"name": "Acme"}}
    data: {"delta": "We", "type": "text"}
    data: {"delta": " currently", "type": "text"}
    data: {"delta": " have...", "type": "text"}
    data: {"type": "done"}
    ```
    
    Progress events are emitted **while the turn is running** so a harness chat UI can show steps (model wait, thinking, tool calls) instead of a silent wait. Unknown event types should be ignored so older clients stay compatible.
    
    | `type` | When | Fields |
    |---|---|---|
    | `run_started` | Immediately, before work begins | `runId` |
    | `status` | Each time the model is about to be called | `phase` (`model`) |
    | `thinking` | While the provider is generating reasoning | `delta` (token-level on Claude streaming; one blob on non-streaming providers) |
    | `tool_call` | Immediately before a tool is dispatched | `name`, `id`, `input` (JSON object when the arguments are JSON, otherwise a string) |
    | `tool_result` | After that tool returns | `name`, `id`, `ok`, `output` (JSON object when the result is JSON, otherwise a string) |
    | `text` | While the provider is writing the reply (Claude streaming), or after the loop if the call was non-streaming | `delta` |
    | `error` | Terminal failure | `message` |
    | `done` | Always last | — |
    
    On Claude, `thinking` and `text` deltas are the provider's own tokens as they are generated. `tool_call` / `tool_result` still fire around tool dispatch. Non-streaming providers keep the previous behaviour (thinking as one blob after the call; reply text chunked at the end).
    
    On failure, a terminal error event precedes `done`:
    
    ```
    data: {"type": "error", "message": "Workflow 'foo' was not found."}
    data: {"type": "done"}
    ```
    
    > **Note:** because SSE commits a `200` response and headers before the first token, an unknown workflow code on the sync path surfaces as a terminal `error` event rather than a `404`. Use the async path if you need a hard `404` for an unresolved code.
    
    ### `POST /workflows/{code}/run/async` — asynchronous (fire-and-forget)
    
    Creates the run at status `Queued`, enqueues a background job, and returns immediately.
    
    Response `202 Accepted`:
    
    ```json
    {
      "runId": "44291...",
      "status": "queued"
    }
    ```
    
    Returns `404 Not Found` if the workflow code does not resolve within the brain.
    
    The engine executes the run in the background (`Queued → Running → Completed / Failed`). A run settles `Failed` (not `Completed`) when the model hits a terminal limit — the workflow's `max-turns` cap is exhausted, or the final `output-tokens` attempt stops with `max_tokens` and no further retry remains — as well as on transport / API errors and cancellation. If a `callbackUrl` was supplied, a webhook is POSTed on completion:
    
    ```http
    POST https://app.example.com/brain/callbacks/run-complete
    Content-Type: application/json
    
    {
      "runId": "44291...",
      "status": "complete"
    }
    ```
    
    `status` is `complete` or `failed`. Webhook delivery is retried on transient failure; a persistent failure is logged but does not fail the run. Results are always retrievable via telemetry.
    
    #### Async callback SSRF rules
    
    Outbound `callbackUrl` delivery is SSRF-hardened (same rules as declared-tool
    `api.path` webhooks — see BRA201 §4.3):
    
    | Rule | Behaviour |
    |---|---|
    | Scheme | `https` required. In Development only, `http://localhost` and `http://127.0.0.1` (any port) are also allowed. |
    | Host allowlist | Optional per-brain list from `brain-compose.yml` `allowed-callback-domains`. When set, the callback host must match an entry exactly (case-insensitive; no wildcards). When omitted, any public host is allowed. |
    | IP blocklist | Always applied after DNS resolution: private, loopback, link-local, and cloud metadata ranges (e.g. `169.254.169.254`) are blocked in all environments. |
    | Redirects | Automatic redirect following is disabled on the callback HTTP client. |
    | Rejection | An unsafe `callbackUrl` marks the run `Failed` and no outbound POST is made. A `SYSTEM_CHANGE` inbox entry (`PROCESSED`) is created with the denied URL, reason, workflow code, and run id. |
    
    Configure harness callback hosts in `brain-compose.yml` before using async runs:
    
    ```yaml
    allowed-callback-domains:
      - app.example.com
    ```
    
    ---
    
    ## Chat Sessions
    
    A synchronous run is a **chat session**: it is the *same* run for the whole conversation. Each turn appends to that run's message history, and the engine replays the run's own transcript as context on every subsequent turn — so the assistant remembers the conversation without you resending it. There is no separate session id: the **run id** (from the `run_started` event) *is* the session.
    
    **Lifecycle.** A session moves through:
    
    ```
    Running  →  AwaitingInput  ⇄  Running (next turn)  →  Completed
                        │
                        └──────────→  Completed (explicit close, or inactivity timeout)
    ```
    
    After each successful turn the run settles at `AwaitingInput` (open) with an `expiresDateUtc`. It is closed to `Completed` when you call `complete`, or automatically when its inactivity timeout passes (see [Session timeout](#session-timeout)). Manual **Run eval** can target a `Completed`, `Failed`, or `AwaitingInput` run (BRA207). Automatic evals still fire on `Completed`.
    
    **Cost and billing.** Each turn (including a sync call that leaves the run `AwaitingInput`) recalculates the run's LLM `CostCents` from its messages. OpenRouter turns that stored provider-billed `usage.cost` on every token-bearing message use that sum; otherwise cost is tokens × date-effective `LlmPrices` for the run's model (`openrouter` + catalogue id for OpenRouter). Daily time-based charges include open sessions: the night job bills `RunSeconds - BilledSeconds` and then raises `BilledSeconds`, so a chat that stays open is charged that day and a later continuation only bills the unbilled remainder.
    
    ### `POST /runs/{runId}/messages` — continue a session
    
    Posts the next user message to an open session and streams the turn as SSE, in the identical wire format to `/workflows/{code}/run/sync` (including a leading `run_started`). The run reuses its own entity / unit-of-work scope; the only per-turn input is the message.
    
    ```json
    {
      "inputMessage": "And what about next quarter?"
    }
    ```
    
    Validated before the stream commits, so these are real HTTP statuses:
    
    | Status | When |
    |---|---|
    | `200` (stream) | The session is open (`AwaitingInput`) and the turn is streaming. |
    | `404 Not Found` | No run with that id belongs to the brain. |
    | `409 Conflict` | The run has a turn in progress, or is `Completed` / `Failed` and can no longer be continued. |
    
    A turn started here re-arms the session's `expiresDateUtc` from the moment it finishes, so an actively used session never times out.
    
    ### `POST /runs/{runId}/stop` — stop an in-flight turn
    
    Stops the current turn if it is `Queued` or `Running` and leaves the session **open** (`AwaitingInput`) so you can send another message. This is not the same as `complete`: the run is not closed and is not evaluated automatically.
    
    Response `200 OK`:
    
    ```json
    {
      "runId": "44291...",
      "status": "AwaitingInput"
    }
    ```
    
    | Status | When |
    |---|---|
    | `200 OK` | The turn was stopped, or the run had already settled (idempotent). |
    | `404 Not Found` | No run with that id belongs to the brain. |
    
    Stopping aborts the in-flight turn, including any model request that is still in progress. Any assistant text already written stays on the run. The session timeout is re-armed from the moment of the stop. A connected SSE stream ends once the turn leaves `Queued` / `Running`.
    
    A client disconnect on `/run/sync` or `/messages` (idle timeout, closed socket) still **fails** the run. If a turn may run longer than the connection can stay open, use `/run/async` instead of relying on a dropped sync stream.
    
    To close the session after stopping, call `POST /runs/{runId}/complete`.
    
    ### `POST /runs/{runId}/complete` — close a session
    
    Closes an open session, transitioning it to `Completed` so it becomes eligible for
    learning evaluation (BRA207 / BRA091). If the brain has a `workflowrun:complete`
    workflow with `trigger-mode: automatic`, an eval is enqueued. If only
    `trigger-mode: manual` (or omitted) is configured, use the admin UI **Run eval**
    button on the run detail page (or `POST /brains/{instance}/runs/{runId}/eval` on
    the Management API).
    
    Response `200 OK`:
    
    ```json
    {
      "runId": "44291...",
      "status": "Completed"
    }
    ```
    
    Idempotent: closing an already-`Completed` session also returns `200`. Returns `404 Not Found` when no such run belongs to the brain, and `409 Conflict` when the run cannot be closed in its current state (e.g. a turn is still in progress — call `stop` first if you need to close immediately).
    
    ### Session timeout
    
    An open session that is neither continued nor closed is swept to `Completed` once its `expiresDateUtc` passes, so abandoned chats do not linger. The inactivity window is set per workflow via the `session-timeout` frontmatter field (in minutes; see BRA201); when a workflow declares none, the engine default of **30 minutes** applies. The window is measured from the end of the most recent turn and re-armed on every continuation.
    
    ---
    
    ## Telemetry
    
    ### `GET /runs/{id}/telemetry` — run telemetry (OTEL)
    
    Returns the full telemetry for a workflow run, projected to the [OpenTelemetry Semantic Conventions for Generative AI](https://opentelemetry.io/docs/specs/semconv/gen-ai/). Each persisted turn becomes a span; token usage maps to `gen_ai.usage.*` and tool calls to `gen_ai.tool.*`.
    
    Response `200 OK`:
    
    ```json
    {
      "runId": "44291...",
      "workflowId": "9c1a...",
      "entityId": "3f0c...",
      "unitOfWorkId": "7b2d...",
      "status": "Completed",
      "createdAt": "2026-07-09T07:10:00Z",
      "completedAt": "2026-07-09T07:10:04Z",
      "resource": {
        "gen_ai.system": "telos-brain",
        "gen_ai.request.model": "anthropic/claude-sonnet-4-6",
        "telos.thinking.mode": "effort"
      },
      "totals": {
        "gen_ai.usage.input_tokens": 1820,
        "gen_ai.usage.output_tokens": 430,
        "gen_ai.embeddings.count": 2,
        "telos.turns.used": 3,
        "telos.turns.max": 15
      },
      "spans": [...]
    }
    ```
    
    Resource / totals extensions (Telos-specific, alongside GenAI semantic conventions):
    
    | Attribute | Notes |
    |---|---|
    | `gen_ai.request.model` | Fully-qualified model the run executed against (`provider/model`) |
    | `gen_ai.embeddings.count` | Embeddings generated in the run (always present on `totals`). OTEL standardises `gen_ai.embeddings.dimension.count` (vector size) only; this is the count of embeddings produced. |
    | `telos.thinking.mode` | Workflow thinking mode (`none` \| `adaptive` \| `extended` \| `effort`) |
    | `telos.turns.used` | Completed assistant loop steps (excludes retries / `max_tokens` attempts) |
    | `telos.turns.max` | Effective max-turns cap for the run (workflow value or engine default 10) |
    
    Span attributes:
    
    | Attribute | Notes |
    |---|---|
    | `gen_ai.message.role` | `user` \| `assistant` \| `tool` |
    | `gen_ai.message.content` | Message content |
    | `gen_ai.usage.input_tokens` / `output_tokens` | Per-turn token counts |
    | `gen_ai.usage.cache_read_input_tokens` / `cache_creation_input_tokens` | Present only when the provider reports prompt-cache usage |
    | `gen_ai.tool.name` / `gen_ai.tool.call.id` | Present only on tool-call and tool-result turns |
    | `gen_ai.embeddings.count` | Embeddings generated for this turn (usually the assistant tool-call row). Omitted when unused. |
    | `gen_ai.response.finish_reason` | Provider stop reason on assistant turns (`end_turn` \| `tool_use` \| `max_tokens` \| ...) |
    | `gen_ai.request.max_tokens` | The output token cap the attempt ran with; doubles per output-token retry |
    | `error.message` | Present only on a failed / truncated assistant attempt |
    
    An output-token retry (see BRA201 `output-tokens`, the ordered per-attempt cap list) is not merged away: each attempt is its own assistant span carrying its `finish_reason` (`max_tokens` on a truncated attempt), the `max_tokens` cap it used and its consumed tokens, so a three-cap list that keeps truncating yields two truncated attempt spans before the final one. If that final attempt is still `max_tokens`, the run status is `Failed`.
    
    Returns `404 Not Found` if the run does not belong to the brain.
    
    ### `GET /units-of-work/{id}/telemetry` — unit-of-work telemetry
    
    Merges the unit of work's context and data logs into a single sequential stream.
    
    **Ordering:** by event `date`, then record type (Context before Data) for identical timestamps, then `createdAt`.
    
    Response `200 OK` — array of entries. Fields not applicable to a record type are `null`:
    
    ```json
    [
      {
        "recordType": "Context",
        "date": "2026-07-09T07:06:00Z",
        "source": "agent",
        "title": "Draft created",
        "message": "Initial draft generated from template",
        "type": null,
        "body": null,
        "createdAt": "2026-07-09T07:06:00Z"
      },
      {
        "recordType": "Data",
        "date": "2026-07-09T07:06:30Z",
        "source": "tool:crm_lookup",
        "title": null,
        "message": null,
        "type": "tool_response",
        "body": "{ ... }",
        "createdAt": "2026-07-09T07:06:30Z"
      }
    ]
    ```
    
    Returns `404 Not Found` if the unit of work does not belong to the brain.
    
    ---
    
    ## Endpoint Summary
    
    | Method | Path | Purpose | Success |
    |---|---|---|---|
    | `POST` | `/workflows/{code}/run/sync` | Run workflow, stream SSE, open a chat session | `200` (stream) |
    | `POST` | `/workflows/{code}/run/async` | Queue workflow run | `202` |
    | `POST` | `/runs/{id}/messages` | Continue an open chat session (stream SSE) | `200` (stream) |
    | `POST` | `/runs/{id}/stop` | Stop an in-flight turn and leave the session open | `200` |
    | `POST` | `/runs/{id}/complete` | Close an open chat session | `200` |
    | `GET` | `/runs/{id}/telemetry` | Run telemetry (OTEL GenAI) | `200` |
    | `GET` | `/units-of-work/{id}/telemetry` | Merged context/data telemetry | `200` |