docs(sdk): clarify sendAction semantics for actions-not-turns

Update the sendAction docstrings on TriggerChatTransport (browser) and
AgentChat (server) to reflect TRI-9118: actions fire hydrateMessages
and onAction only — no run(), no turn lifecycle hooks. The returned
stream is empty for void onAction returns and carries the model
response when onAction returns a StreamTextResult.

Author: ericallam

packages/trigger-sdk/src/v3/chat-client.ts

@@ -468,14 +468,22 @@ export class AgentChat<TAgent = unknown> {
   /**
    * Send a custom action to the agent.
    *
-   * Actions wake the agent, fire the `onAction` hook (which can modify
-   * conversation history via `chat.history.*`), then trigger a normal
-   * `run()` turn so the LLM responds to the updated state.
+   * Actions are not turns. They wake the agent, fire `hydrateMessages`
+   * (if configured) and `onAction` only — no `onTurnStart` /
+   * `prepareMessages` / `onBeforeTurnComplete` / `onTurnComplete`, no
+   * `run()` invocation.
    *
    * The action payload is validated against the agent's `actionSchema`
-   * on the backend.
+   * on the backend. Use `chat.history.*` inside `onAction` to mutate
+   * state. To produce a model response from the action, return a
+   * `StreamTextResult` (or `string` / `UIMessage`) from `onAction` —
+   * the returned stream is auto-piped over this stream. When `onAction`
+   * returns `void`, the action is side-effect-only and the returned
+   * stream completes immediately with `trigger:turn-complete`.
    *
-   * @returns A `ChatStream` for the agent's response.
+   * @returns A `ChatStream`. For void actions the stream completes
+   * immediately. For actions that return a model response, the stream
+   * carries the assistant chunks.
    *
    * @example
    * ```ts

packages/trigger-sdk/src/v3/chat.ts

@@ -763,8 +763,11 @@ export class TriggerChatTransport implements ChatTransport<UIMessage> {
 
   /**
    * Send a custom action chunk (for `chat.agent`'s `actionSchema` /
-   * `onAction` hook). Returns the agent's response stream just like
-   * `sendMessages`.
+   * `onAction` hook). Actions are not turns — only `hydrateMessages`
+   * and `onAction` fire on the agent side. The returned stream
+   * carries any model response `onAction` produced (when it returns a
+   * `StreamTextResult`); for `void`-returning side-effect-only actions
+   * the stream completes immediately with `trigger:turn-complete`.
    */
   sendAction = async (
     chatId: string,