feat(host-service): prototype direct Claude SDK sessions

Closed
BR
4mo ago
+12676-90

What

Archives the working direct Claude Agent SDK approach to live host-owned sessions. It includes the host session manager, sequence journal and WebSocket stream, shared protocol/fold package, mobile session UI, relay/path support, packaged-host validation, and deterministic tests.

Decision

Both the direct SDK approach and the ACP adapter approach work. The comparison is not conclusive enough to claim that one implementation is generally better: ACP moves meaningful normalization and lifecycle logic into the adapter, while direct SDK integration keeps that control in Superset.

We are proceeding with ACP for now because a shared protocol gives us a faster route to supporting more agents. This remains limiting: ACP does not remove agent-specific behavior, capability gaps, adapter lag, or extension metadata. A third viable architecture is a custom channel per agent, accepting separate integrations instead of forcing every agent through one protocol.

This PR is intentionally opened as an archival implementation record and will be closed rather than merged.

Verification

  • bun run typecheck: 33/33 tasks passed
  • Focused direct-SDK/session/mobile/relay suite: 93 passed, 0 failed
  • Biome and repository lint checks passed; the repository-wide git-ref scan was run partitioned because the single root scan exceeded the local command timeout
Open in Stage

Summary by cubic

Prototype direct Claude Agent SDK sessions with host-owned lifecycle, a shared session protocol, and a new mobile thread UI, wired through relay and desktop for live streaming. Adds a session WebSocket, tRPC endpoints, and CI checks to ensure the packaged host is correct and does not bundle Claude again.

  • New Features

    • Host service: ClaudeSessionManager with input queue, sequence journal, deterministic cursors, and WS stream; new sessions tRPC router; resolves system claude executable and builds a clean SDK env; terminal env now records provenance.
    • Shared protocol: new @superset/session-protocol with API shapes, event envelopes, opaque message cursors, fold to a timeline, and client subscribeToSession with reconnect.
    • Mobile: workspace session list and thread screen (composer, timeline, pending permissions/dialogs/elicitations), stream reconnection, and Maestro flows for core, offline, retry, and relay recovery; adds EXPO_PUBLIC_RELAY_URL.
    • Relay/desktop/CLI: relay path handling fixed for encoded host IDs; desktop build excludes @anthropic-ai/claude-agent-sdk* and adds a packaged-host smoke test; new validate:packaged-host script; CLI host spawn is injectable for tests.

  • Dependencies

    • Upgrade @anthropic-ai/sdk to 0.93.0.
    • Add @anthropic-ai/claude-agent-sdk to @superset/host-service and @superset/session-protocol.
    • Add @superset/session-protocol to mobile.
    • Add bun-types for test builds.

Summary by CodeRabbit

  • New Features
    • Added mobile Claude sessions with streaming conversations, session history, model and permission controls.
    • Added interactive permission, question, and authorization prompts, including tool-use approvals.
    • Added resilient session and relay connectivity with offline states, retries, recovery, and interruption handling.
    • Added host-managed session APIs, paginated history, and real-time event streaming.
  • Accessibility
    • Improved workspace row accessibility labels and test coverage.
  • Bug Fixes
    • Improved workspace association during host offline/online transitions.
    • Improved relay routing for encoded host identifiers.
  • Tests
    • Added extensive mobile, desktop, relay, host-service, and end-to-end validation coverage.