[feat] Add Channels (ongoing and far from properly tested)

[junaway]

Context

An Agenta agent can be reached from the product and from the API. It cannot be reached from where people already talk. This branch adds a channels domain: a platform conversation arrives over HTTP, gets matched to a connection and a space, gets checked against a permission rule, runs an agent, and gets an answer posted back on the same thread.

Three channels live on it. Slack, in two installation models. A bridge, for a platform we do not implement in process, reached over HTTP with a shared secret. And an Agenta channel, which needs no platform credentials at all, which is what let the whole path be proven on a laptop before any real platform was involved.

The title is accurate and the draft status is deliberate. The most recent wave is merged and has never run against a real deployment. 83 integration and acceptance tests are written and none has executed, because no running stack has ever carried this schema. Nothing about a seam is proven yet.

Changes

The domain follows the house layering. core/channels/ holds the DTOs, the service and the adapter port. dbs/postgres/channels/ holds the DAO. apis/fastapi/channels/ holds the routes, split into an authenticated router and a public ingress. Adapters live under core/channels/adapters/<channel>/, and the composition root builds one registry that every caller shares.

One adapter port, per channel. An adapter declares what it can do and what it needs to be given, verifies an inbound signature, parses a payload into a neutral event, and renders an outbound answer. Everything else is shared. That is what makes a second platform a folder rather than a project.

Permission is deny first, and it can name a kind rather than a room. A grant carries an effect and matches either a specific space or a whole class of them. The class case is the one that mattered: a direct message is the first thing an operator tries, and a space that has never been opened cannot be pre approved by name.

Slack setup, in the order a human does the work. The blocking defect was reachability, not capability. The manifest a person needs before they own anything sat behind a route that required something to already exist:

GET /channels/connections/{connection_id}/setup   404s until a connection exists
GET /channels/catalog/channels/{channel}/setup/   needs only a channel name

The paste form renders from the channel's own declaration rather than from field names written into a component, so a second platform's form is its declaration and nothing else. Values route to the vault or to the connection row by the declared secret flag, never by name.

Two installation models, one adapter. A customer builds an app in their own workspace from the manifest and pastes back what it gives them. Or they install the app we own in one click over OAuth. The signing secret is per app, not per installation, so a hosted connection stores a bot token and nothing else, and the adapter resolves its verification secret from the connection for one model and from the deployment for the other. A deployment that sets no hosted credentials does not offer that button at all and refuses the route with a reason rather than a stack trace.

The bridge shows the operator both halves of its exchange. It mints its own signing secret on create and returns it once, beside the URL we post to. It is the only credential in the system we issue rather than receive.

The defect this domain kept producing

Four capabilities shipped here that worked and could not be reached, and every test suite passed each time. The most recent was found in this branch's last clean up phase:

# api/entrypoints/channel_adapters.py
adapters={"slack": ..., "mock": ..., "agenta": ...}   # bridge absent
# api/oss/src/apis/fastapi/channels/ingress.py
adapter = self.adapter_registry.get(channel)          # raises on a miss

So POST /bridge/events/ answered 404 for every request in every composition root, and the outbox worker could not deliver a reply. Every bridge test passed, because every bridge test builds its own registry with the bridge in it. The registry's own comment said it was missing.

The fix is one line. The guard is the useful part: a test now fails when a channel has a contract suite but neither a registration in the real factory nor a written exemption. The verification phase after the final merge found nothing dead and nothing test only, which is a first for this domain, and that guard is why.

Tests and notes

• API unit: 3194 passed, 8 skipped. Channels contributes 642 of them and they need nothing running.
• Web unit: 55 passed across the channels settings and state folders. Typecheck clean for both apps.
• Integration and acceptance: 65 and 18 collected, 0 run. They need a deployment carrying this schema and no stack has had one. This is the single biggest gap in the branch, and it is why the PR is a draft.
• 6 errors in unit/sessions/test_stream_fill_missing_postgres.py come from main, not from here. It is a unit test that opens a Postgres connection and does not guard, so it errors rather than skips.
• This branch carries the development tunnel work already open as a separate draft PR ([chore] Extend ngrok to split general ingress and mounts #6010). If that one merges first, this diff shrinks by those commits.
• The Python client is stale. It carries the channels routes from an earlier wave but not this one's setup or install routes. The TypeScript client was regenerated over the merged surface and is current.
• The org wide Enterprise Grid install path is written to mirror the ingress and has never seen a real payload. It fails as a bare 401 that is indistinguishable from a bad secret, so nothing will report it. Both the code and the finding record say so.
• Design notes, the finding ledger and the wave plans live under docs/design/channels-research/v2/. They are most of the added line count.

What to QA

Nothing here can be exercised without a deployment, and two of the settings get registered with Slack, so they are expensive to change afterwards.

Before bringing it up. Set a reserved tunnel domain, because Slack stores both URLs and an address that rotates on restart invalidates both. Point AGENTA_API_URL at that same domain, because the OAuth callback composes from configuration while the manifest composes from the request. Set all three of SLACK_CLIENT_ID, SLACK_CLIENT_SECRET and SLACK_SIGNING_SECRET, or none: the hosted button hides unless all three are present, which is a check rather than a bug.

Register these in the app:

request URL    https://<domain>/api/channels/slack/events/
redirect URL   https://<domain>/api/channels/catalog/channels/slack/callback/

Run the 83 written tests before creating any app. They cost minutes and they fail closer to a cause than a manual flow does.

• Open Settings then Channels on the tunnel host, not on localhost. A page browsed on localhost produces a manifest carrying a localhost request URL. Slack accepts it and no event ever arrives, so the symptom is silence.
• Copy the manifest, build the app, install it, paste the three values back. The connection is created only if auth.test passes, the token lands in the vault and never on the connection row, and a wrong token leaves nothing behind and shows Slack's own reason.
• Allow the agent on direct messages, then send it a direct message and get an answer. That is the milestone this branch is aiming at, and it is the case the permission model could not express before.
• Install the hosted app into a second workspace in one click and reach the same result.
• Create a bridge connection and confirm the response shows its secret and its URL once. Drive the same conversation through it and compare the reply to the in process one.
• Regression: with no hosted credentials set, the install button is absent and the install route answers 404 with a sentence.

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Actions	Updated (UTC)
agenta-documentation	Blocked		Aug 14, 2026 5:56pm

[junaway]

WIP -- @mahmoud

[Copilot]

Copilot wasn't able to review this pull request because it exceeds the maximum number of files (300). Try reducing the number of changed files and requesting a review from Copilot again.

[coderabbitai]

Important

Review skipped

Draft detected.

Please check the settings in the CodeRabbit UI or the .coderabbit.yaml file in this repository. To trigger a single review, invoke the @coderabbitai review command.

⚙️ Run configuration

Configuration used: Repository YAML (base), Organization UI (inherited)

Review profile: CHILL

Plan: Pro Plus

Run ID: f70a56e2-4a7b-4bc8-a926-4e0474033d66

You can disable this status message by setting the reviews.review_status to false in the CodeRabbit configuration file.

Use the checkbox below for a quick retry:

• 🔍 Trigger review

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands.}