Skip to content

bridge: add GATEWAY_* aliases with SLACK_* fallback (phase 2) #191

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
benvinegar merged 1 commit into from
Mar 1, 2026
Merged

bridge: add GATEWAY_* aliases with SLACK_* fallback (phase 2) #191

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
127 changes: 106 additions & 21 deletions .env.schema
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -35,21 +35,38 @@ OPENCODE_ZEN_API_KEY=
# @sensitive=false @type=string
BAUDBOT_MODEL=

# ── Slack ────────────────────────────────────────────────────────────────────
# ── Slack / Gateway bridge ───────────────────────────────────────────────────

# Slack bot OAuth token (required for direct Socket Mode, optional in broker mode)
# Preferred naming: GATEWAY_*
# Legacy naming: SLACK_* (still supported)
# If both are set, GATEWAY_* takes precedence.

# Gateway bot OAuth token (preferred; required for direct Socket Mode, optional in broker mode)
# @type=string(startsWith=xoxb-)
# @docs("Create a Slack app", https://api.slack.com/apps)
GATEWAY_BOT_TOKEN=

# Legacy alias for GATEWAY_BOT_TOKEN
# @type=string(startsWith=xoxb-)
SLACK_BOT_TOKEN=

# Slack app-level token (Socket Mode; optional in broker mode)
# Gateway app-level token (preferred; Socket Mode; optional in broker mode)
# @type=string(startsWith=xapp-)
GATEWAY_APP_TOKEN=

# Legacy alias for GATEWAY_APP_TOKEN
# @type=string(startsWith=xapp-)
SLACK_APP_TOKEN=

# Comma-separated Slack user IDs allowed to interact with the agent
# Comma-separated Slack user IDs allowed to interact with the agent (preferred)
# Optional — if unset, all workspace members can interact.
# @sensitive=false @type=string
# @example="U01ABCDEF,U02GHIJKL"
GATEWAY_ALLOWED_USERS=

# Legacy alias for GATEWAY_ALLOWED_USERS
# @sensitive=false @type=string
# @example="U01ABCDEF,U02GHIJKL"
SLACK_ALLOWED_USERS=

# ── Experimental Feature Flag ───────────────────────────────────────────────
Expand Down Expand Up @@ -93,9 +110,13 @@ SENTRY_ORG=
# @sensitive=false @type=string(startsWith=C)
SENTRY_CHANNEL_ID=

# ── Slack Channels (optional) ───────────────────────────────────────────────
# ── Gateway / Slack Channels (optional) ─────────────────────────────────────

# Additional monitored channel (responds to all messages, not just @mentions)
# Additional monitored channel (preferred; responds to all messages, not just @mentions)
# @sensitive=false @type=string(startsWith=C)
GATEWAY_CHANNEL_ID=

# Legacy alias for GATEWAY_CHANNEL_ID
# @sensitive=false @type=string(startsWith=C)
SLACK_CHANNEL_ID=

Expand All @@ -106,49 +127,93 @@ SLACK_CHANNEL_ID=
# @docs(https://kernel.computer)
KERNEL_API_KEY=

# ── Slack Broker Registration (optional) ─────────────────────────────────────
# ── Gateway/Slack Broker Registration (optional) ────────────────────────────

# Slack broker base URL
# Gateway broker base URL (preferred)
# @sensitive=false @type=url
GATEWAY_BROKER_URL=

# Legacy alias for GATEWAY_BROKER_URL
# @sensitive=false @type=url
SLACK_BROKER_URL=

# Slack workspace/team ID registered with broker
# Gateway workspace/team ID registered with broker (preferred)
# @sensitive=false @type=string(startsWith=T)
GATEWAY_BROKER_WORKSPACE_ID=

# Legacy alias for GATEWAY_BROKER_WORKSPACE_ID
# @sensitive=false @type=string(startsWith=T)
SLACK_BROKER_WORKSPACE_ID=

# Server X25519 private key (base64)
# Gateway server X25519 private key (base64, preferred)
# @type=string
GATEWAY_BROKER_SERVER_PRIVATE_KEY=

# Legacy alias for GATEWAY_BROKER_SERVER_PRIVATE_KEY
# @type=string
SLACK_BROKER_SERVER_PRIVATE_KEY=

# Server X25519 public key (base64)
# Gateway server X25519 public key (base64, preferred)
# @sensitive=false @type=string
GATEWAY_BROKER_SERVER_PUBLIC_KEY=

# Legacy alias for GATEWAY_BROKER_SERVER_PUBLIC_KEY
# @sensitive=false @type=string
SLACK_BROKER_SERVER_PUBLIC_KEY=

# Server Ed25519 private signing key (base64)
# Gateway server Ed25519 private signing key (base64, preferred)
# @type=string
GATEWAY_BROKER_SERVER_SIGNING_PRIVATE_KEY=

# Legacy alias for GATEWAY_BROKER_SERVER_SIGNING_PRIVATE_KEY
# @type=string
SLACK_BROKER_SERVER_SIGNING_PRIVATE_KEY=

# Server Ed25519 public signing key (base64)
# Gateway server Ed25519 public signing key (base64, preferred)
# @sensitive=false @type=string
GATEWAY_BROKER_SERVER_SIGNING_PUBLIC_KEY=

# Legacy alias for GATEWAY_BROKER_SERVER_SIGNING_PUBLIC_KEY
# @sensitive=false @type=string
SLACK_BROKER_SERVER_SIGNING_PUBLIC_KEY=

# Broker X25519 public key (base64)
# Gateway broker X25519 public key (base64, preferred)
# @sensitive=false @type=string
GATEWAY_BROKER_PUBLIC_KEY=

# Legacy alias for GATEWAY_BROKER_PUBLIC_KEY
# @sensitive=false @type=string
SLACK_BROKER_PUBLIC_KEY=

# Broker Ed25519 public signing key (base64)
# Gateway broker Ed25519 public signing key (base64, preferred)
# @sensitive=false @type=string
GATEWAY_BROKER_SIGNING_PUBLIC_KEY=

# Legacy alias for GATEWAY_BROKER_SIGNING_PUBLIC_KEY
# @sensitive=false @type=string
SLACK_BROKER_SIGNING_PUBLIC_KEY=

# Broker-issued bearer token for broker API auth (required for broker pull mode)
# Gateway broker-issued bearer token for broker API auth (preferred; required for broker pull mode)
# @type=string
GATEWAY_BROKER_ACCESS_TOKEN=

# Legacy alias for GATEWAY_BROKER_ACCESS_TOKEN
# @type=string
SLACK_BROKER_ACCESS_TOKEN=

# Optional broker token expiration timestamp (ISO-8601)
# Optional gateway broker token expiration timestamp (ISO-8601, preferred)
# @sensitive=false @type=string
GATEWAY_BROKER_ACCESS_TOKEN_EXPIRES_AT=

# Legacy alias for GATEWAY_BROKER_ACCESS_TOKEN_EXPIRES_AT
# @sensitive=false @type=string
SLACK_BROKER_ACCESS_TOKEN_EXPIRES_AT=

# Optional broker token scopes (comma-separated)
# Optional gateway broker token scopes (comma-separated, preferred)
# @sensitive=false @type=string
GATEWAY_BROKER_ACCESS_TOKEN_SCOPES=

# Legacy alias for GATEWAY_BROKER_ACCESS_TOKEN_SCOPES
# @sensitive=false @type=string
SLACK_BROKER_ACCESS_TOKEN_SCOPES=

Expand All @@ -163,15 +228,35 @@ GITHUB_IGNORED_USERS=
# @sensitive=false @type=string
BAUDBOT_AGENT_VERSION=

# Broker pull cadence in milliseconds (default: 3000)
# Gateway broker pull cadence in milliseconds (preferred; default: 3000)
# @sensitive=false @type=number
GATEWAY_BROKER_POLL_INTERVAL_MS=3000

# Legacy alias for GATEWAY_BROKER_POLL_INTERVAL_MS
# @sensitive=false @type=number
SLACK_BROKER_POLL_INTERVAL_MS=3000

# Max messages to lease per inbox pull request (default: 10)
# Gateway max messages to lease per inbox pull request (preferred; default: 10)
# @sensitive=false @type=number
GATEWAY_BROKER_MAX_MESSAGES=10

# Legacy alias for GATEWAY_BROKER_MAX_MESSAGES
# @sensitive=false @type=number
SLACK_BROKER_MAX_MESSAGES=10

# Dedupe cache TTL in milliseconds (default: 20 minutes)
# Gateway long-poll wait window in seconds (preferred; default: 20, max: 25)
# @sensitive=false @type=number
GATEWAY_BROKER_WAIT_SECONDS=20

# Legacy alias for GATEWAY_BROKER_WAIT_SECONDS
# @sensitive=false @type=number
SLACK_BROKER_WAIT_SECONDS=20

# Gateway dedupe cache TTL in milliseconds (preferred; default: 20 minutes)
# @sensitive=false @type=number
GATEWAY_BROKER_DEDUPE_TTL_MS=1200000

# Legacy alias for GATEWAY_BROKER_DEDUPE_TTL_MS
# @sensitive=false @type=number
SLACK_BROKER_DEDUPE_TTL_MS=1200000

Expand Down
91 changes: 57 additions & 34 deletions CONFIGURATION.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -37,11 +37,16 @@ The agent also uses an SSH key (`~/.ssh/id_ed25519`) for git push. Setup generat

| Variable | Description | How to get it |
|----------|-------------|---------------|
| `SLACK_BOT_TOKEN` | Slack bot OAuth token (required for direct Socket Mode; ignored by broker pull mode) | Create a Slack app at [api.slack.com/apps](https://api.slack.com/apps). Under **OAuth & Permissions**, add bot scopes: `app_mentions:read`, `chat:write`, `channels:history`, `channels:read`, `reactions:write`, `im:history`, `im:read`, `im:write`. Install the app to your workspace and copy the **Bot User OAuth Token**. |
| `SLACK_APP_TOKEN` | Slack app-level token (required for Socket Mode; not used by broker pull mode) | In your Slack app settings → **Basic Information** → **App-Level Tokens**, create a token with `connections:write` scope. |
| `SLACK_ALLOWED_USERS` | Comma-separated Slack user IDs | **Optional** — if not set, all workspace members can interact. Find your Slack user ID: click your profile → "..." → "Copy member ID". Example: `U01ABCDEF,U02GHIJKL` |
| `GATEWAY_BOT_TOKEN` | **Preferred** bot OAuth token for Socket Mode (ignored by broker pull mode) | Create a Slack app at [api.slack.com/apps](https://api.slack.com/apps). Under **OAuth & Permissions**, add bot scopes: `app_mentions:read`, `chat:write`, `channels:history`, `channels:read`, `reactions:write`, `im:history`, `im:read`, `im:write`. Install the app to your workspace and copy the **Bot User OAuth Token**. |
| `SLACK_BOT_TOKEN` | Legacy alias for `GATEWAY_BOT_TOKEN` (still supported) | Same token as above; migrate to `GATEWAY_BOT_TOKEN` over time. |
| `GATEWAY_APP_TOKEN` | **Preferred** app-level token for Socket Mode | In your Slack app settings → **Basic Information** → **App-Level Tokens**, create a token with `connections:write` scope. |
| `SLACK_APP_TOKEN` | Legacy alias for `GATEWAY_APP_TOKEN` (still supported) | Same token as above; migrate to `GATEWAY_APP_TOKEN` over time. |
| `GATEWAY_ALLOWED_USERS` | **Preferred** comma-separated Slack user IDs allowlist | **Optional** — if not set, all workspace members can interact. Find your Slack user ID: click your profile → "..." → "Copy member ID". Example: `U01ABCDEF,U02GHIJKL` |
| `SLACK_ALLOWED_USERS` | Legacy alias for `GATEWAY_ALLOWED_USERS` (still supported) | Same value as above; migrate to `GATEWAY_ALLOWED_USERS` over time. |

If you're using Slack broker mode (`SLACK_BROKER_*` vars), the runtime uses broker pull delivery and does not require Socket Mode callbacks.
If both alias forms are present, `GATEWAY_*` takes precedence.

If you're using broker mode (`GATEWAY_BROKER_*` preferred, `SLACK_BROKER_*` legacy), the runtime uses broker pull delivery and does not require Socket Mode callbacks.

If you're using the Slack broker OAuth flow, register this server after install:

Expand Down Expand Up @@ -105,32 +110,50 @@ The integration token only provides read access to pages/databases explicitly sh

| Variable | Description | How to get it |
|----------|-------------|---------------|
| `SLACK_CHANNEL_ID` | Additional monitored channel | If set, the bridge responds to all messages in this channel (not just @mentions). |
| `GATEWAY_CHANNEL_ID` | **Preferred** additional monitored channel | If set, the bridge responds to all messages in this channel (not just @mentions). |
| `SLACK_CHANNEL_ID` | Legacy alias for `GATEWAY_CHANNEL_ID` (still supported) | Same value as above; migrate to `GATEWAY_CHANNEL_ID` over time. |

### Slack Broker Registration (optional)

Set by `sudo baudbot broker register` when using brokered Slack OAuth flow.

| Variable | Description |
|----------|-------------|
| `SLACK_BROKER_URL` | Broker base URL |
| `SLACK_BROKER_WORKSPACE_ID` | Slack workspace/team ID (`T...`) |
| `SLACK_BROKER_SERVER_PRIVATE_KEY` | Server X25519 private key (base64) |
| `SLACK_BROKER_SERVER_PUBLIC_KEY` | Server X25519 public key (base64) |
| `SLACK_BROKER_SERVER_SIGNING_PRIVATE_KEY` | Server Ed25519 private signing key (base64) |
| `SLACK_BROKER_SERVER_SIGNING_PUBLIC_KEY` | Server Ed25519 public signing key (base64) |
| `SLACK_BROKER_PUBLIC_KEY` | Broker X25519 public key (base64) |
| `SLACK_BROKER_SIGNING_PUBLIC_KEY` | Broker Ed25519 public signing key (base64) |
| `SLACK_BROKER_ACCESS_TOKEN` | Broker-issued bearer token for broker API auth (required for broker pull mode runtime) |
| `SLACK_BROKER_ACCESS_TOKEN_EXPIRES_AT` | ISO timestamp for broker token expiry (recommended; runtime exits if expired) |
| `SLACK_BROKER_ACCESS_TOKEN_SCOPES` | Comma-separated broker token scopes |
| `GATEWAY_BROKER_URL` | **Preferred** broker base URL |
| `SLACK_BROKER_URL` | Legacy alias for `GATEWAY_BROKER_URL` (still supported) |
| `GATEWAY_BROKER_WORKSPACE_ID` | **Preferred** Slack workspace/team ID (`T...`) |
| `SLACK_BROKER_WORKSPACE_ID` | Legacy alias for `GATEWAY_BROKER_WORKSPACE_ID` |
| `GATEWAY_BROKER_SERVER_PRIVATE_KEY` | **Preferred** server X25519 private key (base64) |
| `SLACK_BROKER_SERVER_PRIVATE_KEY` | Legacy alias for `GATEWAY_BROKER_SERVER_PRIVATE_KEY` |
| `GATEWAY_BROKER_SERVER_PUBLIC_KEY` | **Preferred** server X25519 public key (base64) |
| `SLACK_BROKER_SERVER_PUBLIC_KEY` | Legacy alias for `GATEWAY_BROKER_SERVER_PUBLIC_KEY` |
| `GATEWAY_BROKER_SERVER_SIGNING_PRIVATE_KEY` | **Preferred** server Ed25519 private signing key (base64) |
| `SLACK_BROKER_SERVER_SIGNING_PRIVATE_KEY` | Legacy alias for `GATEWAY_BROKER_SERVER_SIGNING_PRIVATE_KEY` |
| `GATEWAY_BROKER_SERVER_SIGNING_PUBLIC_KEY` | **Preferred** server Ed25519 public signing key (base64) |
| `SLACK_BROKER_SERVER_SIGNING_PUBLIC_KEY` | Legacy alias for `GATEWAY_BROKER_SERVER_SIGNING_PUBLIC_KEY` |
| `GATEWAY_BROKER_PUBLIC_KEY` | **Preferred** broker X25519 public key (base64) |
| `SLACK_BROKER_PUBLIC_KEY` | Legacy alias for `GATEWAY_BROKER_PUBLIC_KEY` |
| `GATEWAY_BROKER_SIGNING_PUBLIC_KEY` | **Preferred** broker Ed25519 public signing key (base64) |
| `SLACK_BROKER_SIGNING_PUBLIC_KEY` | Legacy alias for `GATEWAY_BROKER_SIGNING_PUBLIC_KEY` |
| `GATEWAY_BROKER_ACCESS_TOKEN` | **Preferred** broker-issued bearer token for broker API auth (required for broker pull mode runtime) |
| `SLACK_BROKER_ACCESS_TOKEN` | Legacy alias for `GATEWAY_BROKER_ACCESS_TOKEN` |
| `GATEWAY_BROKER_ACCESS_TOKEN_EXPIRES_AT` | **Preferred** ISO timestamp for broker token expiry (runtime exits if expired) |
| `SLACK_BROKER_ACCESS_TOKEN_EXPIRES_AT` | Legacy alias for `GATEWAY_BROKER_ACCESS_TOKEN_EXPIRES_AT` |
| `GATEWAY_BROKER_ACCESS_TOKEN_SCOPES` | **Preferred** comma-separated broker token scopes |
| `SLACK_BROKER_ACCESS_TOKEN_SCOPES` | Legacy alias for `GATEWAY_BROKER_ACCESS_TOKEN_SCOPES` |
| `GITHUB_IGNORED_USERS` | Optional comma-separated GitHub logins to ignore when forwarding broker GitHub events (`baudbot-agent` is always ignored) |
| `SLACK_BROKER_POLL_INTERVAL_MS` | Inbox poll interval in milliseconds (default: `3000`) |
| `SLACK_BROKER_MAX_MESSAGES` | Max leased messages per poll request (default: `10`) |
| `SLACK_BROKER_WAIT_SECONDS` | Long-poll wait window for `/api/inbox/pull` (default: `20`, set `0` for immediate short-poll, max `25`) |
| `SLACK_BROKER_DEDUPE_TTL_MS` | Dedupe cache TTL in milliseconds (default: `1200000`) |
| `GATEWAY_BROKER_POLL_INTERVAL_MS` | **Preferred** inbox poll interval in milliseconds (default: `3000`) |
| `SLACK_BROKER_POLL_INTERVAL_MS` | Legacy alias for `GATEWAY_BROKER_POLL_INTERVAL_MS` |
| `GATEWAY_BROKER_MAX_MESSAGES` | **Preferred** max leased messages per poll request (default: `10`) |
| `SLACK_BROKER_MAX_MESSAGES` | Legacy alias for `GATEWAY_BROKER_MAX_MESSAGES` |
| `GATEWAY_BROKER_WAIT_SECONDS` | **Preferred** long-poll wait window for `/api/inbox/pull` (default: `20`, set `0` for immediate short-poll, max `25`) |
| `SLACK_BROKER_WAIT_SECONDS` | Legacy alias for `GATEWAY_BROKER_WAIT_SECONDS` |
| `GATEWAY_BROKER_DEDUPE_TTL_MS` | **Preferred** dedupe cache TTL in milliseconds (default: `1200000`) |
| `SLACK_BROKER_DEDUPE_TTL_MS` | Legacy alias for `GATEWAY_BROKER_DEDUPE_TTL_MS` |
| `BAUDBOT_AGENT_VERSION` | Optional override for broker observability `meta.agent_version` (otherwise read from `~/.pi/agent/baudbot-version.json` when available) |

If both alias forms are set, `GATEWAY_BROKER_*` takes precedence.

Broker mode also emits best-effort context usage telemetry in inbox pull `meta` by reading `~/.pi/agent/context-usage.json` (written by the `context` extension on session start/turn end/tool results).

### Kernel (Cloud Browsers)
Expand Down Expand Up @@ -223,25 +246,25 @@ ANTHROPIC_API_KEY=sk-ant-...

# GitHub: authenticate with `sudo -u baudbot_agent gh auth login`

# Slack
SLACK_BOT_TOKEN=xoxb-...
SLACK_APP_TOKEN=xapp-...
SLACK_ALLOWED_USERS=U01ABCDEF,U02GHIJKL
# Gateway bridge (legacy SLACK_* aliases are still supported)
GATEWAY_BOT_TOKEN=xoxb-...
GATEWAY_APP_TOKEN=xapp-...
GATEWAY_ALLOWED_USERS=U01ABCDEF,U02GHIJKL
SENTRY_CHANNEL_ID=C0987654321

# Slack broker registration (optional, set by: sudo baudbot broker register)
SLACK_BROKER_URL=https://broker.example.com
SLACK_BROKER_WORKSPACE_ID=T0123ABCD
# Gateway broker registration (optional, set by: sudo baudbot broker register)
GATEWAY_BROKER_URL=https://broker.example.com
GATEWAY_BROKER_WORKSPACE_ID=T0123ABCD
# Optional broker auth token fields (set by broker register when provided)
# SLACK_BROKER_ACCESS_TOKEN=...
# SLACK_BROKER_ACCESS_TOKEN_EXPIRES_AT=2026-02-22T22:15:00.000Z
# SLACK_BROKER_ACCESS_TOKEN_SCOPES=slack.send,inbox.pull,inbox.ack
# GATEWAY_BROKER_ACCESS_TOKEN=...
# GATEWAY_BROKER_ACCESS_TOKEN_EXPIRES_AT=2026-02-22T22:15:00.000Z
# GATEWAY_BROKER_ACCESS_TOKEN_SCOPES=slack.send,inbox.pull,inbox.ack
# Optional GitHub bot/user filters for broker-delivered GitHub webhook events
# GITHUB_IGNORED_USERS=dependabot[bot],renovate[bot]
SLACK_BROKER_POLL_INTERVAL_MS=3000
SLACK_BROKER_MAX_MESSAGES=10
SLACK_BROKER_WAIT_SECONDS=20
SLACK_BROKER_DEDUPE_TTL_MS=1200000
GATEWAY_BROKER_POLL_INTERVAL_MS=3000
GATEWAY_BROKER_MAX_MESSAGES=10
GATEWAY_BROKER_WAIT_SECONDS=20
GATEWAY_BROKER_DEDUPE_TTL_MS=1200000

# Experimental features (required for email)
# BAUDBOT_EXPERIMENTAL=1
Expand Down
4 changes: 2 additions & 2 deletions bin/config.sh
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -574,8 +574,8 @@ fi

# ── Validation ───────────────────────────────────────────────────────────────

if [ -z "${ENV_VARS[SLACK_ALLOWED_USERS]:-}" ]; then
warn "SLACK_ALLOWED_USERS not set — all workspace members will be allowed"
if [ -z "${ENV_VARS[GATEWAY_ALLOWED_USERS]:-${ENV_VARS[SLACK_ALLOWED_USERS]:-}}" ]; then
warn "GATEWAY_ALLOWED_USERS/SLACK_ALLOWED_USERS not set — all workspace members will be allowed"
fi

# ── Write config ─────────────────────────────────────────────────────────────
Expand Down
Loading