feat(slack-relay): upload each agent's Claude session to Sessions through relaygate, as the agent
Each Slack thread agent's Claude Code session is now uploaded to Agent Relay Sessions through relaygate, as that agent, so the session is owned by the agent and placed in the pit group (gid 22).
What it does
- When: the agent host uploads after every turn (a thread message or a DM). At startup it also uploads, for every known agent, whatever is past the cursor.
- What: the transcript at
/data/home/.claude/projects/<cwd>/<session>.jsonl, sent as native delivery batches (POST <relaygate>/sessions/v1/delivery/batches,relayhistory-delivery-v1). This is the format the Desktop uses, and relaygate's own acceptance tests write sessions the same way.- A
sessionrecord carries the title<agent> · Slack <channel id> thread <thread ts>, the first prompt, activity times and models. - Each user or assistant message becomes one
session_event. Tool calls appear by name. Tool results and meta lines are skipped.
- A
- Ownership: every request carries the agent's own
rg_token. relaygate gives a new session to its first uploader and that uploader's group, so the owner is the agent and the group is gid 22. The policy'ssessionDefaultsfor gid 22 decide who can read it. - Restart-safe: a per-session cursor (byte offset of the last complete line) lives on the host PVC at
/data/sessions-upload/cursors. - Idempotent: record ids come from the transcript's line uuids, and batch ids are content hashes, so a retry is an exact replay.
- Retries:
- 429 and 503 wait for
Retry-After, capped at 5 minutes. - Other 5xx and network errors back off; after 4 attempts the upload waits for the next turn.
- A relaygate 403 (
relaygate_*) is final for that session. A 403 from Sessions itself is treated as configuration and retried after the next turn. - Transcript text and tokens are never logged.
- 429 and 503 wait for
The Sessions credential
relaygate's /sessions proxy needs a Sessions credential to forward:
- If the caller sends only
Authorization: Bearer rg_…, relaygate forwards itsSESSIONS_TOKEN. When that is unset it answers401 relaygate_unauthenticated.SESSIONS_INTERNAL_SECRETis only used for relay-control's read-token mint routes. (Source: relaygatesrc/sessions.ts,credential().) - The sessions-pipeline ingest edge accepts only a relay-control user access token (
sh_at_) withrth:sync. Workspace API tokens andrth_*tokens are refused. An access token lasts 24 hours and its refresh token 90 days. A staticSESSIONS_TOKENwould therefore stop working after a day.
So the host holds its own credential (sessions.upload.relayControlUrl plus secrets.sessionsEnrollmentKey):
- An org owner or admin mints a Desktop enrollment key for an uploader user.
- The host exchanges the key once at
/api/v1/auth/enrollment/token. - It stores the rotating session in
/data/sessions-upload/.credential.json(mode 600) and refreshes it through/api/v1/auth/token/refresh. A 401 from the gate triggers one refresh. - Uploads send
X-Relaygate-Token: <agent rg_>withAuthorization: Bearer <sh_at_>. relaygate checks the agent and forwards the credential unchanged.
If relayControlUrl is left empty, uploads fall back to relaygate's SESSIONS_TOKEN.
Chart (slack-relay 0.3.5, agent-relay 0.7.42)
sessions:
upload:
enabled: true # default false; needs relaygate.url
orgId: <relay-control org id>
workspaceId: <relay-control workspace id>
baseUrl: "" # default <relaygate.url>/sessions (the gate's main port)
relayControlUrl: http://<release>-relay-control:8080
secrets:
sessionsEnrollmentKey: { name: slack-relay-sessions, key: enrollment-key }
The chart fails the render if relaygate.url, orgId/workspaceId, or the enrollment Secret (when relayControlUrl is set) is missing. Chart CI gets ci/sessions-values.yaml. The registry gets entry opt.slack-relay.session-upload, and the matrix rows are bumped (slack-relay 0.3.4 becomes planned, as #430 did for the release before it).
Docs
docs/self-hosted-slack-relay.md has a new "Session upload" section and new values rows. In the diagram source and SVG, "session upload: planned" now reads "session upload via relaygate, as the agent". The PNG was not re-rendered (no mermaid CLI here).
Tests
test/sessions-upload.test.ts runs against a fake relaygate Sessions proxy. It covers:
- native format and ownership headers, both with and without a host credential;
- the cursor across a restart, and partial lines held back;
- batch splitting with a cursor per batch;
- byte-identical retries;
- Retry-After on 429 and 503, and the attempt budget;
- relaygate 403 as final, including after a restart, with no content or token in the logs;
- a Sessions 403 that is not final;
- one credential refresh on 401;
- enrollment exchange, then rotating refresh;
- the host hook after a turn and on rejoin, with the agent's token and Slack ids.
Typecheck passes. 48 unit tests pass (the e2e tests are skipped locally). scripts/ci/charts.sh static and registry.mjs check pass.
Not verified
- No upload has been made against a live ingest edge. Two open questions:
- whether the edge accepts this
account_id(sha256 of[orgId, workspaceId]) with an enrollment-key session; - whether a
sessionrecord with nogit_branchor other Desktop-only fields renders the same in the dashboard.
- whether the edge accepts this
- I haven't checked that the slack-relay namespace can reach relay-control; a NetworkPolicy may block it.
🤖 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
Uploads each Slack agent's Claude Code transcript to Agent Relay Sessions through relaygate, as that agent, so the session is owned by the agent and lands in its group (the pit, gid 22). Session upload was previously marked planned; it's now opt-in via new sessions.upload.* values.
Behavior
- The host uploads after every turn and at startup for any unsent content, as native delivery batches (
POST <relaygate>/sessions/v1/delivery/batches) using the agent's ownrg_token. - A per-session byte cursor on the host volume makes restarts safe, and record and batch ids derive from transcript content, so retries are exact replays.
- 429/503 honor
Retry-After; other failures back off and retry on the next turn; a relaygate 403 is final for that session. Uploads never reject, so the queue can't wedge. Message text and tokens are never logged. - Batches are measured in UTF-8 bytes with the envelope and session record reserved; uploaded timestamps are formatted to stay clear of Sessions' Luhn scrub.
- The Sessions credential is the host's own: it exchanges a Desktop enrollment key at relay-control and refreshes the rotating session, falling back to relaygate's
SESSIONS_TOKENwhenrelayControlUrlis empty.
Rollout notes
- Chart render fails when upload is enabled without
relaygate.url,orgId/workspaceId, or the enrollment secret (whenrelayControlUrlis set). - Versions bump to slack-relay 0.3.5 and agent-relay 0.7.43; docs, the registry, and tests are updated, including a fake relaygate proxy.
- Not verified: no upload has been run against a live ingest edge, and the slack-relay namespace's path to relay-control may be blocked by a NetworkPolicy.