feat(slack-relay): read-only Sessions tools for the agents, governed by relaygate

Merged
KH
3d ago
+1062-23

Gives slack-relay's per-thread agents read-only access to Agent Relay Sessions as MCP tools (mcp__sessions__*: list_sessions, get_session, get_session_turns, search_sessions). relaygate governs every read.

To enable (chart 0.3.7)

sessions:
  upload:            # reused; required even if upload.enabled is false
    orgId: <org id>
    workspaceId: <workspace id>
    relayControlUrl: http://relay-control
  mcp:
    enabled: true    # the single new value; default false
secrets:
  sessionsEnrollmentKey: { name: <secret>, key: enrollment-key }   # same as upload

relaygate.url must be set. The uploader user needs rth:read in the workspace (Desktop enrollment sessions have it via DEVICE_SCOPES). mcp__sessions is added to the agents' allowedTools automatically. A new image build is needed (new src/ files).

Design: the credential never reaches the agent

  • src/sessions-read.ts: SessionReadCredential mints a read token at relay-control as the uploader user (POST /api/v1/workspaces/<ws>/session-read/session, refreshed via /session-read/refresh, re-minted if a refresh is refused). It shares the uploader's EnrollmentCredential instance, so sh_rt_ rotation never races, and it stays in memory only. SessionsReadProxy is a loopback (127.0.0.1) proxy. It serves GET on relaygate's read routes only, and only to callers holding a current agent rg_ token. It forwards with X-Relaygate-Token: <agent rg_> plus Authorization: Bearer <read token>, and it sets workspace= itself. On a 401 it re-mints the token and retries once. Responses are capped at 4 MiB.
  • src/sessions-mcp.ts: a stdio MCP server, no dependencies, that Claude Code starts per agent. Its env holds only SESSIONS_PROXY_URL and the agent's own RELAY_AGENT_TOKEN, which is already in the agent's .mcp.json for relaycast. Output is capped at 24 000 characters, with long strings cut. A 403 is reported as "Not permitted" and never retried. Tool descriptions mark transcript content as untrusted data.
  • Why a proxy and not a file or env var: .mcp.json sits in the agent's workdir, which Read(./**) allows. The MCP child runs as the same uid. So anything handed to the MCP server could be read by the agent. Keeping the token in the host means that, at worst, an agent can read as itself.

relaygate verification (origin/main source)

  • src/app.ts authenticate: on /sessions/*, when X-Relaygate-Token is present, the principal is that rg_ agent (principalFor(agent), viaControl=false). The control-principal branch runs only when no X-Relaygate-Token is sent. So with the header, reads are decided as gid 22 for a slack-bridge agent.
  • src/sessions.ts: credential() forwards the caller's non-rg_ Authorization unchanged. GET /v1/sessions and GET /v1/events?q= are filtered with canRead(principal). /:id/{events,turns,metadata,brief,...} and events?session= go through gateRead. Aggregates are not proxied.
  • No escalation: the effective principal is the agent, and the upstream read API also scopes to the token's user, so the agent reads at most what both may read. The only escalation path would be the agent holding the read token itself (relaygate would then treat it as the uploader user), and this design prevents that.
  • relay-control (session-read.ts, openapi): any member with a live rth:read session may mint, limited to 30 requests/min per user and workspace. The TTL is set by the read API, so the host follows accessTokenExpiresAt. reader_kind is device for an sh_at_ bearer.

What pit agents can and can't read (gid 22; people/Desktop uploads in gid 11 with acl 22:r)

  • Can read: pit-owned (22) sessions, and gid-11 sessions through the 22:r ACL.
  • Cannot read:
    • sessions of any group with no read entry for 22 (people/admin-only groups, guests);
    • sessions where a sessionOverrides entry or a ceiling removes 22;
    • unowned sessions that never came through relaygate, such as uploads made before relaygate was in the path;
    • aggregate views (not proxied).

Docs: docs/self-hosted-slack-relay.md ("Agent session reads").

Tests

test/sessions-mcp.test.ts (11 tests) runs against a fake relaygate and a fake relay-control. It covers:

  • the route for each tool and the agent's rg_ in X-Relaygate-Token;
  • the read credential absent from tool output, logs and the MCP config/env;
  • a 403 reported as not permitted with no retry;
  • output size bounds and the proxy cap;
  • the proxy's route, method and token allowlist;
  • the 401 re-mint;
  • the mint/refresh logic;
  • a stdio end-to-end run.

Full suite: 70/70. Also run: tsc, plus helm lint/template on the new ci/sessions-mcp-values.yaml and the existing CI values.

Not verified

  • Live end to end against a real relay-control and read API. In particular, whether the read API accepts the minted token with workspace= when called through relaygate's /sessions.
  • Whether the backend serves /brief. get_session falls back to brief: null on 404/501.

Not merged, not deployed.

🤖 Generated with Claude Code


Autofix with [code]smith
Open in [code]smith · Need help on this PR? Tag @codesmith-bot with what you need.


Summary by cubic

Gives each slack-relay per-thread agent read-only access to Agent Relay Sessions through MCP tools (mcp__sessions__*: list_sessions, get_session, get_session_turns, search_sessions), with relaygate deciding every read as the agent.

Reads go to relaygate's Sessions proxy with the agent's own rg_ token, so a pit agent sees only sessions its group may read. The host mints a short-lived read credential as the uploader user and keeps it in memory; a loopback proxy adds it to forwarded requests, so the credential never reaches the agent's .mcp.json or MCP server environment. A relaygate 403 is reported as "Not permitted" without retry, and responses are capped at 24,000 characters per call.

Deployment

  • Chart 0.3.7 adds sessions.mcp.enabled (default false). It reuses sessions.upload's orgId, workspaceId, and relayControlUrl and secrets.sessionsEnrollmentKey, which are now required even with upload disabled; the uploader user needs rth:read in the workspace.
  • mcp__sessions is added to the agents' allowedTools automatically, and relaygate.url must be set.
  • agent-relay bumps to 0.7.45 to pin slack-relay 0.3.7; the requirements registry and self-hosted docs track the new option.