Skip to content

armgit / eve

Public Imported from GitHub
0

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.mdx
index 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
### Dispatch
diff --git a/docs/channels/overview.mdx b/docs/channels/overview.mdx
index 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 au
After 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 messages
Channels 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.mdx
index 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).