The Open Framework for Building Agents
docs: clarify channel audiences (#3390)
Chad Hietala088753ca5495
diff --git a/docs/channels/chat-sdk.mdx b/docs/channels/chat-sdk.mdxindex 86fd6f001..e5c88098e 100644--- a/docs/channels/chat-sdk.mdx+++ b/docs/channels/chat-sdk.mdx@@ -79,6 +79,13 @@ export const { bot, channel, send } = chatSdkChannel({Use `routes` when a provider requires a fixed URL or when you are migrating an existing endpoint without changing the provider's settings.+## Audience++Workspace-visible threads are `public`. DMs and private or external threads+are `private`; threads without a known visibility are `unknown`. The audience+controls observability content capture, not access to the thread. See+[Audience](./overview#audience) for the shared channel model.+## How the channel handles messages### Dispatchdiff --git a/docs/channels/overview.mdx b/docs/channels/overview.mdxindex 4866d28a0..3f4981590 100644--- a/docs/channels/overview.mdx+++ b/docs/channels/overview.mdx@@ -13,6 +13,19 @@ eve ships a base HTTP channel plus first-class platform channels, and you can auAfter a channel normalizes input, eve runs the same agent runtime regardless of where the message came from. Tools and instructions do not need channel-specific logic.+## Audience++When a channel creates a session, it assigns an observability audience:+`public`, `private`, or `unknown`. The audience controls trace content capture,+not who may call the channel. Each channel uses the visibility information it+has; `unknown` is the safe default when it cannot classify a conversation.++Route auth controls access and supplies the session principal. See [Auth &+route protection](../guides/auth-and-route-protection) for principal types and+authorization. See the [default eve HTTP channel](./eve#audience) for its+mapping, or [custom channels](./custom#conversation-audience) to classify your+own.+## Overlapping messagesChannels default to `turnPolicy: "steer"`. When an accepted message arrives while a turn is active, eve first durably buffers the message, then cooperatively cancels the active turn and starts a replacement turn. The cancelled turn emits `turn.cancelled` followed by `session.waiting`; the replacement starts with a new turn ID. Output already streamed and completed side effects are not rolled back.diff --git a/docs/channels/slack.mdx b/docs/channels/slack.mdxindex 4521b4508..d73ecf74c 100644--- a/docs/channels/slack.mdx+++ b/docs/channels/slack.mdx@@ -137,6 +137,14 @@ Check the delivery path in order so you can identify where a Slack event stops:| A preview request receives an authentication page or protection error | Check whether the branch domain is exempt or the direct Slack request URL includes `x-vercel-protection-bypass`. Slack cannot complete an interactive Vercel Authentication challenge. | Add a Deployment Protection Exception for the branch domain, or add the automation bypass query parameter to a Slack app that uses environment-variable credentials. || The webhook reaches the deployment but the agent does not reply | Open the project's Vercel runtime logs, then inspect the session in **Agent Runs** when your team has access. | Use the first missing or failed stage to narrow the issue to channel dispatch, the agent run, or outbound Slack delivery. |+## Audience++Slack public channels are `public`; DMs, group DMs, and private channels are+`private`. When an inbound event does not identify the conversation type, eve+checks Slack and treats an ambiguous or failed lookup as `private`. The audience+controls observability content capture, not access to the channel. See+[Audience](./overview#audience) for the shared channel model.+## How the channel handles inbound events### Message hooks@@ -501,7 +509,7 @@ The private authorization button uses the label **Sign in**, so long connection### Proactive sessions-Start a session without an inbound message through `ctx.to(slack, target).send(message, { auth })` from another channel, or `to(slack, target).send(message, { auth })` from a schedule `run` handler. The proactive target shape is `{ channelId, installationTeamId?, threadTs?, initialMessage? }`. Set `installationTeamId` to the app installation workspace when a function-form bot token must select an installation. This sends turn input to the agent; it is not a direct Slack post.+Start a session without an inbound message through `ctx.to(slack, target).send(message, { auth })` from another channel, or `to(slack, target).send(message, { auth })` from a schedule `run` handler. The proactive target shape is `{ channelId, installationTeamId?, threadTs?, initialMessage?, audience? }`. It defaults to `unknown`; pass `audience` only when the caller already knows the destination's visibility. Set `installationTeamId` to the app installation workspace when a function-form bot token must select an installation. This sends turn input to the agent; it is not a direct Slack post.To post without invoking the model, use `ctx.thread.post(...)` in an inbound Slack handler or `channel.thread.post(...)` in an `events` handler. Use `callSlackApi(...)` where no Slack channel context exists. For application-managed retries and deduplication, see [Durable cross-channel notifications](../patterns/durable-cross-channel-notifications).