feat(slack-relay): read-only Sessions tools for the agents, governed by relaygate
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:SessionReadCredentialmints 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'sEnrollmentCredentialinstance, sosh_rt_rotation never races, and it stays in memory only.SessionsReadProxyis a loopback (127.0.0.1) proxy. It serves GET on relaygate's read routes only, and only to callers holding a current agentrg_token. It forwards withX-Relaygate-Token: <agent rg_>plusAuthorization: Bearer <read token>, and it setsworkspace=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 onlySESSIONS_PROXY_URLand the agent's ownRELAY_AGENT_TOKEN, which is already in the agent's.mcp.jsonfor 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.jsonsits in the agent's workdir, whichRead(./**)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.tsauthenticate: on/sessions/*, whenX-Relaygate-Tokenis present, the principal is thatrg_agent (principalFor(agent),viaControl=false). The control-principal branch runs only when noX-Relaygate-Tokenis 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/sessionsandGET /v1/events?q=are filtered withcanRead(principal)./:id/{events,turns,metadata,brief,...}andevents?session=go throughgateRead. 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 liverth:readsession may mint, limited to 30 requests/min per user and workspace. The TTL is set by the read API, so the host followsaccessTokenExpiresAt.reader_kindisdevicefor ansh_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
sessionOverridesentry 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_inX-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_sessionfalls back tobrief: nullon 404/501.
Not merged, not deployed.
🤖 Generated with Claude Code
![Autofix with [code]smith](https://pr-comments-assets.blacksmith.sh/codesmith/autofix-with-codesmith-dark-3x.png)
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(defaultfalse). It reusessessions.upload'sorgId,workspaceId, andrelayControlUrlandsecrets.sessionsEnrollmentKey, which are now required even with upload disabled; the uploader user needsrth:readin the workspace. mcp__sessionsis added to the agents'allowedToolsautomatically, andrelaygate.urlmust be set.agent-relaybumps to 0.7.45 to pin slack-relay 0.3.7; the requirements registry and self-hosted docs track the new option.