fix: fix agent stream contract with cloudonix (#504)

docs/configurations/agent-uuid.mdx

@@ -29,7 +29,7 @@ Use the Agent UUID for workflow-level routes such as:
 
 - `POST /api/v1/public/agent/workflow/{workflow_uuid}`
 - `POST /api/v1/public/agent/test/workflow/{workflow_uuid}`
-- `wss://<your-host>/api/v1/agent-stream/{agent_uuid}`
+- `wss://<your-host>/api/v1/agent-stream/{provider}/{agent_uuid}`
 
 <Note>
 Do not confuse the Agent UUID with an API Trigger node UUID (`trigger_path`).

docs/integrations/telephony/agent-stream.mdx

@@ -5,7 +5,7 @@ description: "Stream audio to a Dograh agent over a WebSocket"
 
 ## Overview
 
-Agent Stream is a WebSocket endpoint that lets a telephony provider point its media stream at a single URL and drive a Dograh agent run. The agent UUID in the URL selects the agent; provider-specific identifiers in the query string (for Cloudonix: `Domain`) tell Dograh which stored telephony configuration to use for that call. The bearer token and other credentials are never passed in the URL — they live in the stored configuration and are used by Dograh to validate the session and to issue provider API calls (hangup, transfer) during the call.
+Agent Stream is a WebSocket endpoint that lets a telephony provider point its media stream at a single URL and drive a Dograh agent run. The agent UUID in the URL selects the agent, and the provider path segment selects the streaming protocol. Provider-specific identifiers come from the stream protocol itself. For Cloudonix, Dograh reads the domain from the `start.accountSid` field, then uses the matching stored telephony configuration to validate the session and issue provider API calls (hangup, transfer) during the call.
 
 This is useful when:
 
@@ -23,15 +23,15 @@ This is useful when:
 ## Endpoint
 
 ```
-wss://app.dograh.com/api/v1/agent-stream/{agent_uuid}
+wss://app.dograh.com/api/v1/agent-stream/{provider}/{agent_uuid}
 ```
 
-`{agent_uuid}` is the agent's stable UUID (see [Get the Agent UUID](#get-the-agent-uuid) below). On self-hosted deployments, replace `app.dograh.com` with your backend host.
+`{provider}` is the registered provider name, currently `cloudonix`. `{agent_uuid}` is the agent's stable UUID (see [Get the Agent UUID](#get-the-agent-uuid) below). On self-hosted deployments, replace `app.dograh.com` with your backend host.
 
 ## Prerequisites
 
 - A Dograh agent (workflow) — published or in draft is fine
-- A Cloudonix telephony configuration in your Dograh organization whose `domain_id` matches the `Domain` you pass on the URL. Dograh uses the bearer token from this configuration to validate the call session and to issue provider API calls (hangup, transfer).
+- A Cloudonix telephony configuration in your Dograh organization whose `domain_id` matches the `accountSid` Cloudonix sends in the stream `start` message. Dograh uses the bearer token from this configuration to validate the call session and to issue provider API calls (hangup, transfer).
 
 ## Get the Agent UUID
 
@@ -41,25 +41,17 @@ To find and copy it in the UI, see [Agent UUID](/configurations/agent-uuid).
 
 ## Connect to the WebSocket
 
-### URL parameters
+### Path parameters
 
 | Param | Required | Description |
 | --- | --- | --- |
 | `provider` | Yes | Provider name. Currently only `cloudonix` is supported. |
-| `Domain` | Yes (cloudonix) | Cloudonix domain ID. Dograh uses this to look up the matching stored telephony configuration and retrieve the bearer token used for provider API calls. |
-| `callId` / `CallSid` | No | Call identifier from your side; persisted on the workflow run's `gathered_context` as `call_id`. The Cloudonix call SID used for streaming is taken from the `start` event payload, not this param. |
-| `from` | No | Caller phone number, persisted on the workflow run as `caller_number`. |
-| `to` | No | Called phone number, persisted on the workflow run as `called_number`. |
+| `agent_uuid` | Yes | Stable UUID of the Dograh agent to run. |
 
 ### Cloudonix example
 
 ```
-wss://app.dograh.com/api/v1/agent-stream/{agent_uuid}
-  ?provider=cloudonix
-  &Domain={CLOUDONIX_DOMAIN_ID}
-  &callId={CALL_ID}
-  &from=+15555550100
-  &to=+15555550199
+wss://app.dograh.com/api/v1/agent-stream/cloudonix/{agent_uuid}
 ```
 
 Use this URL inside the CXML `<Stream>` your Cloudonix Voice Application returns when the call needs to be bridged to the Dograh agent:
@@ -68,13 +60,13 @@ Use this URL inside the CXML `<Stream>` your Cloudonix Voice Application returns
 <?xml version="1.0" encoding="UTF-8"?>
 <Response>
   <Connect>
-    <Stream url="wss://app.dograh.com/api/v1/agent-stream/{agent_uuid}?provider=cloudonix&Domain=...&callId=...&from=...&to=..."/>
+    <Stream url="wss://app.dograh.com/api/v1/agent-stream/cloudonix/{agent_uuid}"/>
   </Connect>
   <Pause length="40"/>
 </Response>
 ```
 
-The first two messages on the socket should be Cloudonix's standard `connected` and `start` events (Twilio-compatible framing). Dograh extracts `streamSid` and `callSid` from the `start` event payload, validates the session against Cloudonix using the bearer token from the stored telephony configuration matched by `Domain`, and then begins streaming audio.
+The first two messages on the socket should be Cloudonix's standard `connected` and `start` events (Twilio-compatible framing). Dograh extracts `streamSid`, `callSid`, `session`, `accountSid`, `from`, `to`, `context`, `tracks`, and `mediaFormat` from the `start` event payload. It validates the session against Cloudonix using the bearer token from the stored telephony configuration matched by `accountSid`, then begins streaming audio.
 
 ## Workflow run lifecycle
 
@@ -82,8 +74,10 @@ When the WebSocket is accepted, Dograh:
 
 1. Looks up the workflow by `agent_uuid`
 2. Runs a quota check against the workflow's owning user
-3. Creates a new `WorkflowRun` (`call_type=inbound`, `mode=cloudonix`, name `WR-AGS-XXXXXXXX`) with the `from`/`to` numbers stamped on `initial_context`, the `callId`/`CallSid` stored as `call_id` on `gathered_context`, and `Domain` recorded under the run's `inbound_webhook` log
-4. Transitions the run to `running` and starts the agent pipeline
+3. Creates a new `WorkflowRun` (`call_type=inbound`, `mode=cloudonix`, name `WR-AGS-XXXXXXXX`)
+4. Transitions the run to `running`
+5. Reads and validates the Cloudonix `start` message, then stamps the `from`/`to` numbers on `initial_context`, stores `session` as `call_id` on `gathered_context`, and records `accountSid` under the run's `inbound_webhook` log
+6. Starts the agent pipeline
 
 The run is visible under the agent's **Runs** tab as soon as it's minted, just like an inbound or outbound call.
 
@@ -93,9 +87,9 @@ The run is visible under the agent's **Runs** tab as soon as it's minted, just l
 | --- | --- |
 | `1008` | Routing failure — unknown provider, workflow not found, or quota exceeded |
 | `1011` | Server-side failure or unsupported provider for Agent Stream |
-| `4400` | Provider-level handshake error — for cloudonix, missing `Domain`, no matching telephony configuration, missing bearer token on the configuration, malformed `connected`/`start` events, or session validation failed against Cloudonix |
+| `4400` | Provider-level handshake error — for cloudonix, missing `start.accountSid`, no matching telephony configuration, missing bearer token on the configuration, malformed `connected`/`start` events, or session validation failed against Cloudonix |
 
 ## Security notes
 
 - Treat the URL as a secret — the agent UUID itself authorizes the connection. Store and transmit it only over TLS, and avoid logging the raw URL in places where access is broader than your operations team.
-- No bearer tokens or provider secrets are passed in the URL. Provider credentials live in the stored telephony configuration (matched by `Domain` for Cloudonix) and are used server-side by Dograh to validate the session and issue provider API calls.
+- No bearer tokens or provider secrets are passed in the URL. Provider credentials live in the stored telephony configuration (matched by `start.accountSid` for Cloudonix) and are used server-side by Dograh to validate the session and issue provider API calls.