feat(slack-relay): upload each agent's Claude session to Sessions through relaygate, as the agent

Merged
KH
5d ago
+1126-19

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 session record 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.
  • 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's sessionDefaults for 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.

The Sessions credential

relaygate's /sessions proxy needs a Sessions credential to forward:

  • If the caller sends only Authorization: Bearer rg_…, relaygate forwards its SESSIONS_TOKEN. When that is unset it answers 401 relaygate_unauthenticated. SESSIONS_INTERNAL_SECRET is only used for relay-control's read-token mint routes. (Source: relaygate src/sessions.ts, credential().)
  • The sessions-pipeline ingest edge accepts only a relay-control user access token (sh_at_) with rth:sync. Workspace API tokens and rth_* tokens are refused. An access token lasts 24 hours and its refresh token 90 days. A static SESSIONS_TOKEN would therefore stop working after a day.

So the host holds its own credential (sessions.upload.relayControlUrl plus secrets.sessionsEnrollmentKey):

  1. An org owner or admin mints a Desktop enrollment key for an uploader user.
  2. The host exchanges the key once at /api/v1/auth/enrollment/token.
  3. 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.
  4. Uploads send X-Relaygate-Token: <agent rg_> with Authorization: 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 session record with no git_branch or other Desktop-only fields renders the same in the dashboard.
  • 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
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 own rg_ 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_TOKEN when relayControlUrl is empty.

Rollout notes

  • Chart render fails when upload is enabled without relaygate.url, orgId/workspaceId, or the enrollment secret (when relayControlUrl is 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.