Add Claude Code provider integration

Author: sasha-s

.plans/19-claude-code-support-design-review.md

@@ -1,120 +1,120 @@
-# Design Review: Claude Code Support
+# Claude Code Support — Execution Plan
 
-## Summary
+## Goal
 
-T3 Code is clearly being shaped toward multi-provider support, but the current implementation remains codex-first in both contracts and runtime assumptions. Claude Code support should land as a real provider adapter, not as a UI-only toggle.
+Ship `claudeCode` as a first-class provider in the current `apps/server` + `apps/web` stack, with predictable lifecycle behavior, canonical runtime events, and capability-driven UI gating.
 
-## What Already Helps
+## Architecture Fit
 
-- provider service / adapter architecture already exists under `apps/server/src/provider`
-- provider session directory and resume binding already exist
-- runtime events are normalized through canonical provider runtime ingestion
-- the web UI already gestures at unavailable providers in the picker
+This track is intentionally aligned to the current codebase, not legacy `apps/renderer` assumptions.
 
-These are strong foundations.
+### Server runtime path
 
-## Where Codex Still Leaks Through
-
-### Contracts
-
-`ProviderKind` is still effectively locked to Codex, so any provider abstraction above it is narrower than it appears.
+- `apps/server/src/provider/Layers/ClaudeCodeAdapter.ts`
+- `apps/server/src/provider/Services/ClaudeCodeAdapter.ts`
+- `apps/server/src/provider/Layers/ProviderAdapterRegistry.ts`
+- `apps/server/src/provider/Layers/ProviderService.ts`
+- `apps/server/src/provider/Layers/ProviderSessionDirectory.ts`
+- `apps/server/src/provider/Layers/ProviderHealth.ts`
+- `apps/server/src/serverLayers.ts`
+- `apps/server/src/wsServer.ts`
 
-Areas to widen first:
+### Shared contracts / model path
 
 - `packages/contracts/src/orchestration.ts`
 - `packages/contracts/src/provider.ts`
+- `packages/contracts/src/providerRuntime.ts`
 - `packages/contracts/src/model.ts`
-
-### Runtime protocol assumptions
-
-Codex-specific semantics are still embedded in:
-
-- `apps/server/src/codexAppServerManager.ts`
-- `apps/server/src/provider/Layers/CodexAdapter.ts`
-- collaboration mode / effort settings
-- model selection and account handling
-- resume semantics and turn lifecycle mapping
-
-### UI assumptions
-
-The UI already lists `claudeCode` as unavailable, but provider capabilities are not yet modeled deeply enough for different approval semantics, tool event shapes, or model option behavior.
-
-## Recommended Direction
-
-Treat Claude Code support as a canonical provider implementation with a first-class adapter and a capability matrix.
-
-### Phase 1 — widen contracts
-
-- expand `ProviderKind` to include `claudeCode`
-- add provider capability contracts:
-  - model switch mode
-  - approval support
-  - user input support
-  - collaboration / planning support
-  - resume support level
-
-### Phase 2 — add adapter
-
-Introduce:
-
-- `apps/server/src/provider/Layers/ClaudeCodeAdapter.ts`
-- `apps/server/src/provider/Services/ClaudeCodeAdapter.ts`
-
-This adapter should be responsible for:
-
-- session startup
-- send turn
-- interrupt / stop
-- request/approval response mapping
-- event normalization into canonical `ProviderRuntimeEvent`
-
-### Phase 3 — runtime normalization
-
-Ensure `ProviderRuntimeIngestion` stays provider-agnostic by consuming canonical runtime events only.
-
-If Claude requires provider-specific preprocessing, keep that inside the adapter layer.
-
-### Phase 4 — UI enablement
-
-- enable Claude in the provider picker only after the adapter is usable
-- gate unsupported features off capability flags, not hardcoded provider checks
-
-## Capability Matrix to Add
-
-Every provider should declare at least:
-
-- `sessionModelSwitch`
-- `supportsApprovals`
-- `supportsUserInput`
-- `supportsResume`
-- `supportsCollaborationMode`
-- `supportsImageInputs`
-- `supportsReasoningEffort`
-- `supportsServiceTier`
-
-This avoids future branching scattered across `ChatView.tsx`.
-
-## Reentry Feature Implications
-
-Claude support should plug into the proposed reentry engine in two ways:
-
-1. as a runtime signal source through canonical provider events
-2. as an optional recap writer backend once the provider is stable
-
-The recap system should not assume Codex-only event fields or model option semantics.
-
-## Risks
-
-- resume behavior may not match Codex thread recovery semantics
-- approval and tool event taxonomies may be materially different
-- collaboration mode may not have a direct Claude equivalent
-- provider-specific prompt tuning for recap generation could leak into server orchestration if not isolated
-
-## Recommendation
-
-Do **not** bolt Claude Code onto `CodexAppServerManager`. Instead:
-
-- keep Codex-specific runtime logic in Codex modules
-- add provider capability contracts first
-- ship Claude through the existing adapter / registry / service architecture
-- keep recap generation behind a separate model broker so runtime provider and recap writer provider can differ
+- `packages/contracts/src/server.ts`
+- `packages/shared/src/model.ts`
+
+### Web path
+
+- `apps/web/src/components/ChatView.tsx`
+- `apps/web/src/composerDraftStore.ts`
+- `apps/web/src/store.ts`
+- `apps/web/src/session-logic.ts`
+- `apps/web/src/appSettings.ts`
+- `apps/web/src/routes/_chat.settings.tsx`
+- `apps/web/src/wsNativeApi.ts`
+
+## Execution Tracks
+
+### 1. Contracts and capability matrix
+
+- Widen `ProviderKind` to include `claudeCode`.
+- Define provider capability contracts in `packages/contracts/src/provider.ts`:
+  - `sessionModelSwitch`
+  - `supportsApprovals`
+  - `supportsUserInput`
+  - `supportsResume`
+  - `supportsCollaborationMode`
+  - `supportsImageInputs`
+  - `supportsReasoningEffort`
+  - `supportsServiceTier`
+  - `supportsConversationRollback`
+- Extend provider model options in `packages/contracts/src/model.ts`:
+  - Codex: `reasoningEffort`, `fastMode`
+  - Claude Code: `effort`
+- Extend runtime raw-source contracts in `packages/contracts/src/providerRuntime.ts` for Claude-native stream events.
+- Surface provider capabilities through `packages/contracts/src/server.ts` so `server.getConfig` becomes the single source of truth for provider availability + feature gating.
+
+### 2. Server adapter and session lifecycle
+
+- Add a dedicated `ClaudeCodeAdapter` under `apps/server/src/provider`.
+- Keep Codex-specific logic isolated in Codex modules.
+- Use the Claude runtime adapter to own:
+  - session startup / resume
+  - turn dispatch
+  - interrupt / stop
+  - canonical event emission
+  - capability reporting
+- Preserve `ProviderService` as the cross-provider routing layer.
+- Preserve `ProviderSessionDirectory` as the persisted thread → provider binding / resume binding layer.
+- Register Claude in `ProviderAdapterRegistryLive` and `makeServerProviderLayer()`.
+
+### 3. Health checks and WebSocket/API surface
+
+- Extend `ProviderHealthLive` to probe Claude install/auth status alongside Codex.
+- Keep `server.getConfig` as the main transport surface for provider status + capability data.
+- Ensure `server.configUpdated` pushes continue to carry the latest provider status objects.
+- Do not add a parallel Claude-specific RPC surface unless the orchestration path cannot express a required operation.
+
+### 4. Web provider parity
+
+- Drive provider availability from `server.getConfig().providers`, not hardcoded placeholders.
+- Keep `PROVIDER_OPTIONS` as the UI label list, but compute selectable / unavailable providers from server status.
+- Extend settings to support custom Claude model slugs.
+- Extend the composer model / effort controls so they respect provider capabilities.
+- Gate unsupported features via capabilities instead of provider-name checks:
+  - image inputs
+  - plan/default interaction mode
+  - service tier
+  - conversation rollback
+- Keep event rendering provider-agnostic by consuming orchestration projections only.
+
+### 5. Reliability requirements
+
+- Resume / reconnect must rely on persisted provider session bindings, not fragile UI state.
+- Provider restarts must keep behavior deterministic:
+  - no silent provider swapping
+  - no hidden capability fallback without an explicit runtime warning
+- Partial stream handling must continue to produce stable timeline state if a turn is interrupted mid-stream.
+- Session stop / interrupt flows must settle orchestration thread state instead of leaving it ambiguous.
+
+## Current implementation notes
+
+This implementation track favors shared abstractions over one-off branching:
+
+- provider capabilities are shared through contracts and reused by both server and web
+- provider status and capability data flow through `server.getConfig`
+- UI gating uses capability data instead of hardcoded `provider === "codex"` checks where possible
+- Claude support is added through the existing adapter / registry / service architecture instead of special-casing `wsServer`
+
+## Follow-up work after this track
+
+- Persist a thread-level preferred provider so idle threads do not need model-based provider inference.
+- Add richer Claude permission / elicitation bridging if the adapter surface stabilizes enough to expose it predictably.
+- Add Claude image-input support once the runtime path supports structured non-text turn inputs cleanly.
+- Revisit rollback / checkpoint parity if Claude exposes reversible conversation history primitives.
+- Add targeted integration tests for reconnect, restart, and interrupted partial-stream recovery on Claude sessions.

REMOTE.md

@@ -63,3 +63,23 @@ Open from any device in your tailnet:
 `http://<tailnet-ip>:3773`
 
 You can also bind `--host 0.0.0.0` and connect through the Tailnet IP, but binding directly to the Tailnet IP limits exposure.
+
+## 3) Tailnet access in `dev` / `dev-branch`
+
+For the dev runner, prefer an explicit Tailnet host so the injected Vite URL, HMR socket, and app WebSocket URL all use the same remote-friendly address.
+
+```bash
+T3CODE_HOST="$(tailscale ip -4)" \
+T3CODE_NO_BROWSER=1 \
+T3CODE_PORT_OFFSET=20 \
+T3CODE_STATE_DIR=~/.t3/dev-claude-branch \
+./scripts/dev-branch.sh
+```
+
+Then open from another device in your tailnet:
+
+`http://<tailnet-ip>:5753`
+
+If you prefer to land on the server port first, open:
+
+`http://<tailnet-ip>:3793`

apps/server/integration/TestProviderAdapter.integration.ts

@@ -3,6 +3,7 @@ import { randomUUID } from "node:crypto";
 import {
   ApprovalRequestId,
   EventId,
+  PROVIDER_CAPABILITIES_BY_PROVIDER,
   ProviderApprovalDecision,
   ProviderRuntimeEvent,
   RuntimeSessionId,
@@ -35,7 +36,7 @@ export interface TestTurnResponse {
 export type FixtureProviderRuntimeEvent = {
   readonly type: string;
   readonly eventId: EventId;
-  readonly provider: "codex";
+  readonly provider: "codex" | "claudeCode";
   readonly createdAt: string;
   readonly threadId: string;
   readonly turnId?: string | undefined;
@@ -474,9 +475,7 @@ export const makeTestProviderAdapterHarness = (options?: MakeTestProviderAdapter
 
   const adapter: ProviderAdapterShape<ProviderAdapterError> = {
     provider,
-    capabilities: {
-      sessionModelSwitch: "in-session",
-    },
+    capabilities: PROVIDER_CAPABILITIES_BY_PROVIDER[provider],
     startSession,
     sendTurn,
     interruptTurn,

apps/server/package.json

@@ -22,13 +22,15 @@
     "test": "vitest run"
   },
   "dependencies": {
+    "@anthropic-ai/claude-agent-sdk": "^0.2.71",
     "@effect/platform-node": "catalog:",
     "@effect/sql-sqlite-bun": "catalog:",
     "@pierre/diffs": "^1.1.0-beta.16",
     "effect": "catalog:",
     "node-pty": "^1.1.0",
     "open": "^10.1.0",
-    "ws": "^8.18.0"
+    "ws": "^8.18.0",
+    "zod": "^4.3.6"
   },
   "devDependencies": {
     "@effect/language-service": "catalog:",

apps/server/src/main.ts

@@ -9,6 +9,7 @@
 import { Config, Data, Effect, FileSystem, Layer, Option, Path, Schema, ServiceMap } from "effect";
 import { Command, Flag } from "effect/unstable/cli";
 import { NetService } from "@t3tools/shared/Net";
+import { formatHostForUrl, isWildcardHost } from "@t3tools/shared/host";
 import {
   DEFAULT_PORT,
   resolveStaticDir,
@@ -204,12 +205,6 @@ const LayerLive = (input: CliInput) =>
     Layer.provideMerge(ServerConfigLive(input)),
   );
 
-const isWildcardHost = (host: string | undefined): boolean =>
-  host === "0.0.0.0" || host === "::" || host === "[::]";
-
-const formatHostForUrl = (host: string): string =>
-  host.includes(":") && !host.startsWith("[") ? `[${host}]` : host;
-
 export const recordStartupHeartbeat = Effect.gen(function* () {
   const analytics = yield* AnalyticsService;
   const projectionSnapshotQuery = yield* ProjectionSnapshotQuery;

apps/server/src/orchestration/Layers/CheckpointReactor.test.ts

@@ -10,6 +10,7 @@ import {
   EventId,
   MessageId,
   ProjectId,
+  PROVIDER_CAPABILITIES_BY_PROVIDER,
   ThreadId,
   TurnId,
 } from "@t3tools/contracts";
@@ -89,7 +90,7 @@ function createProviderServiceHarness(
     respondToUserInput: () => unsupported(),
     stopSession: () => unsupported(),
     listSessions,
-    getCapabilities: () => Effect.succeed({ sessionModelSwitch: "in-session" }),
+    getCapabilities: () => Effect.succeed(PROVIDER_CAPABILITIES_BY_PROVIDER[providerName]),
     rollbackConversation,
     streamEvents: Stream.fromPubSub(runtimeEventPubSub),
   };