Open-source Grok Bot alternative for named AI teammates. Local-first desktop, web, and mobile clients with per-bot tools, instructions, and memory. Independent fork of T3 Code.
Add Claude Code adapter live layer with error mapping tests
Julius Marminge802cd127d17d
diff --git a/apps/server/src/provider/Layers/ClaudeCodeAdapter.test.ts b/apps/server/src/provider/Layers/ClaudeCodeAdapter.test.tsnew file mode 100644index 000000000..95a9f8fda--- /dev/null+++ b/apps/server/src/provider/Layers/ClaudeCodeAdapter.test.ts@@ -0,0 +1,269 @@+import type {+ ProviderApprovalDecision,+ ProviderRuntimeEvent,+ ProviderSendTurnInput,+ ProviderSession,+ ProviderSessionStartInput,+ ProviderTurnStartResult,+} from "@t3tools/contracts";+import {+ ApprovalRequestId,+ EventId,+ ProviderSessionId,+ ProviderThreadId,+ ProviderTurnId,+} from "@t3tools/contracts";+import { afterAll, assert, it, vi } from "@effect/vitest";+import { assertFailure } from "@effect/vitest/utils";++import { Effect, Fiber, Queue, Stream } from "effect";++import { ProviderAdapterValidationError } from "../Errors.ts";+import { ClaudeCodeAdapter } from "../Services/ClaudeCodeAdapter.ts";+import { type ClaudeCodeRuntime, makeClaudeCodeAdapterLive } from "./ClaudeCodeAdapter.ts";++const asSessionId = (value: string): ProviderSessionId => ProviderSessionId.makeUnsafe(value);+const asTurnId = (value: string): ProviderTurnId => ProviderTurnId.makeUnsafe(value);+const asEventId = (value: string): EventId => EventId.makeUnsafe(value);+const asRequestId = (value: string): ApprovalRequestId => ApprovalRequestId.makeUnsafe(value);++class FakeClaudeRuntime implements ClaudeCodeRuntime {+ private readonly runtimeEventQueue = Effect.runSync(Queue.unbounded<ProviderRuntimeEvent>());+ readonly streamEvents = Stream.fromQueue(this.runtimeEventQueue);++ public startSessionImpl = vi.fn(+ async (input: ProviderSessionStartInput): Promise<ProviderSession> => {+ const now = new Date().toISOString();+ return {+ sessionId: asSessionId("claude-sess-1"),+ provider: "claudeCode",+ status: "ready",+ threadId: ProviderThreadId.makeUnsafe("claude-thread-1"),+ resumeCursor: input.resumeCursor ?? { opaque: "claude-cursor-1" },+ cwd: input.cwd,+ model: input.model,+ createdAt: now,+ updatedAt: now,+ };+ },+ );++ public sendTurnImpl = vi.fn(+ async (_input: ProviderSendTurnInput): Promise<ProviderTurnStartResult> => ({+ threadId: ProviderThreadId.makeUnsafe("claude-thread-1"),+ turnId: asTurnId("claude-turn-1"),+ }),+ );++ public interruptTurnImpl = vi.fn(+ async (_sessionId: ProviderSessionId, _turnId?: ProviderTurnId): Promise<void> => undefined,+ );++ public readThreadImpl = vi.fn(async (_sessionId: ProviderSessionId) => ({+ threadId: ProviderThreadId.makeUnsafe("claude-thread-1"),+ turns: [],+ }));++ public rollbackThreadImpl = vi.fn(+ async (_sessionId: ProviderSessionId, _numTurns: number) => ({+ threadId: ProviderThreadId.makeUnsafe("claude-thread-1"),+ turns: [],+ }),+ );++ public respondToRequestImpl = vi.fn(+ async (+ _sessionId: ProviderSessionId,+ _requestId: ApprovalRequestId,+ _decision: ProviderApprovalDecision,+ ): Promise<void> => undefined,+ );++ public stopSessionImpl = vi.fn((_sessionId: ProviderSessionId) => undefined);+ public listSessionsImpl = vi.fn((): ReadonlyArray<ProviderSession> => []);+ public hasSessionImpl = vi.fn((_sessionId: ProviderSessionId): boolean => false);+ public stopAllImpl = vi.fn(() => undefined);++ async startSession(input: ProviderSessionStartInput): Promise<ProviderSession> {+ return this.startSessionImpl(input);+ }++ async sendTurn(input: ProviderSendTurnInput): Promise<ProviderTurnStartResult> {+ return this.sendTurnImpl(input);+ }++ async interruptTurn(sessionId: ProviderSessionId, turnId?: ProviderTurnId): Promise<void> {+ return this.interruptTurnImpl(sessionId, turnId);+ }++ async readThread(sessionId: ProviderSessionId) {+ return this.readThreadImpl(sessionId);+ }++ async rollbackThread(sessionId: ProviderSessionId, numTurns: number) {+ return this.rollbackThreadImpl(sessionId, numTurns);+ }++ async respondToRequest(+ sessionId: ProviderSessionId,+ requestId: ApprovalRequestId,+ decision: ProviderApprovalDecision,+ ): Promise<void> {+ return this.respondToRequestImpl(sessionId, requestId, decision);+ }++ stopSession(sessionId: ProviderSessionId): void {+ this.stopSessionImpl(sessionId);+ }++ listSessions(): ReadonlyArray<ProviderSession> {+ return this.listSessionsImpl();+ }++ hasSession(sessionId: ProviderSessionId): boolean {+ return this.hasSessionImpl(sessionId);+ }++ stopAll(): void {+ this.stopAllImpl();+ }++ emitRuntimeEvent(event: ProviderRuntimeEvent): void {+ Queue.offerAllUnsafe(this.runtimeEventQueue, [event]);+ }+}++const validationRuntime = new FakeClaudeRuntime();+const validationLayer = it.layer(makeClaudeCodeAdapterLive({ runtime: validationRuntime }));++validationLayer("ClaudeCodeAdapterLive validation", (it) => {+ it.effect("returns validation error for non-claudeCode provider on startSession", () =>+ Effect.gen(function* () {+ const adapter = yield* ClaudeCodeAdapter;+ const result = yield* adapter+ .startSession({+ provider: "codex",+ })+ .pipe(Effect.result);++ assertFailure(+ result,+ new ProviderAdapterValidationError({+ provider: "claudeCode",+ operation: "startSession",+ issue: "Expected provider 'claudeCode' but received 'codex'.",+ }),+ );+ assert.equal(validationRuntime.startSessionImpl.mock.calls.length, 0);+ }),+ );+});++const sessionErrorRuntime = new FakeClaudeRuntime();+sessionErrorRuntime.sendTurnImpl.mockImplementation(async () => {+ throw new Error("Unknown session: claude-sess-missing");+});+const sessionErrorLayer = it.layer(makeClaudeCodeAdapterLive({ runtime: sessionErrorRuntime }));++sessionErrorLayer("ClaudeCodeAdapterLive session errors", (it) => {+ it.effect("maps unknown-session sendTurn errors to ProviderAdapterSessionNotFoundError", () =>+ Effect.gen(function* () {+ const adapter = yield* ClaudeCodeAdapter;+ const result = yield* adapter+ .sendTurn({+ sessionId: asSessionId("claude-sess-missing"),+ input: "hello",+ attachments: [],+ })+ .pipe(Effect.result);++ assert.equal(result._tag, "Failure");+ if (result._tag !== "Failure") {+ return;+ }++ assert.equal(result.failure._tag, "ProviderAdapterSessionNotFoundError");+ if (result.failure._tag !== "ProviderAdapterSessionNotFoundError") {+ return;+ }+ assert.equal(result.failure.provider, "claudeCode");+ assert.equal(result.failure.sessionId, "claude-sess-missing");+ assert.instanceOf(result.failure.cause, Error);+ }),+ );+});++const lifecycleRuntime = new FakeClaudeRuntime();+const lifecycleLayer = it.layer(makeClaudeCodeAdapterLive({ runtime: lifecycleRuntime }));++lifecycleLayer("ClaudeCodeAdapterLive lifecycle", (it) => {+ it.effect("forwards providerOptions and opaque resumeCursor to runtime startSession", () =>+ Effect.gen(function* () {+ const adapter = yield* ClaudeCodeAdapter;+ const resumeCursor = {+ threadId: "provider-thread-opaque",+ sessionAt: "message:42",+ };+ const started = yield* adapter.startSession({+ provider: "claudeCode",+ cwd: "/tmp/claude-workspace",+ model: "claude-sonnet-4",+ resumeCursor,+ providerOptions: {+ claudeCode: {+ binaryPath: "/usr/local/bin/claude",+ permissionMode: "acceptEdits",+ maxThinkingTokens: 4_096,+ },+ },+ });++ assert.equal(started.provider, "claudeCode");+ assert.deepEqual(started.resumeCursor, resumeCursor);+ assert.deepEqual(lifecycleRuntime.startSessionImpl.mock.calls[0]?.[0], {+ provider: "claudeCode",+ cwd: "/tmp/claude-workspace",+ model: "claude-sonnet-4",+ resumeCursor,+ providerOptions: {+ claudeCode: {+ binaryPath: "/usr/local/bin/claude",+ permissionMode: "acceptEdits",+ maxThinkingTokens: 4_096,+ },+ },+ });+ }),+ );++ it.effect("passes through canonical runtime events without remapping", () =>+ Effect.gen(function* () {+ const adapter = yield* ClaudeCodeAdapter;+ const firstEventFiber = yield* Stream.runHead(adapter.streamEvents).pipe(Effect.forkChild);+ const runtimeEvent: ProviderRuntimeEvent = {+ type: "approval.requested",+ eventId: asEventId("evt-claude-approval"),+ provider: "claudeCode",+ sessionId: asSessionId("claude-sess-1"),+ createdAt: new Date().toISOString(),+ requestId: asRequestId("approval-claude-1"),+ requestKind: "command",+ };++ lifecycleRuntime.emitRuntimeEvent(runtimeEvent);+ const firstEvent = yield* Fiber.join(firstEventFiber);++ assert.equal(firstEvent._tag, "Some");+ if (firstEvent._tag !== "Some") {+ return;+ }+ assert.deepEqual(firstEvent.value, runtimeEvent);+ }),+ );+});++afterAll(() => {+ assert.equal(validationRuntime.stopAllImpl.mock.calls.length, 1);+ assert.equal(sessionErrorRuntime.stopAllImpl.mock.calls.length, 1);+ assert.equal(lifecycleRuntime.stopAllImpl.mock.calls.length, 1);+});diff --git a/apps/server/src/provider/Layers/ClaudeCodeAdapter.ts b/apps/server/src/provider/Layers/ClaudeCodeAdapter.tsnew file mode 100644index 000000000..2472695f6--- /dev/null+++ b/apps/server/src/provider/Layers/ClaudeCodeAdapter.ts@@ -0,0 +1,257 @@+/**+ * ClaudeCodeAdapterLive - Scoped live implementation for the Claude Code provider adapter.+ *+ * Wraps a Claude runtime bridge behind the `ClaudeCodeAdapter` service contract+ * and maps runtime failures into the shared `ProviderAdapterError` algebra.+ *+ * @module ClaudeCodeAdapterLive+ */+import type {+ ApprovalRequestId,+ ProviderApprovalDecision,+ ProviderRuntimeEvent,+ ProviderSendTurnInput,+ ProviderSession,+ ProviderSessionId,+ ProviderSessionStartInput,+ ProviderTurnId,+ ProviderTurnStartResult,+} from "@t3tools/contracts";+import { Effect, Layer, Stream } from "effect";++import {+ ProviderAdapterProcessError,+ ProviderAdapterRequestError,+ ProviderAdapterSessionClosedError,+ ProviderAdapterSessionNotFoundError,+ ProviderAdapterValidationError,+ type ProviderAdapterError,+} from "../Errors.ts";+import { type ProviderThreadSnapshot } from "../Services/ProviderAdapter.ts";+import {+ ClaudeCodeAdapter,+ type ClaudeCodeAdapterShape,+} from "../Services/ClaudeCodeAdapter.ts";++const PROVIDER = "claudeCode" as const;++export interface ClaudeCodeRuntime {+ readonly startSession: (input: ProviderSessionStartInput) => Promise<ProviderSession>;+ readonly sendTurn: (input: ProviderSendTurnInput) => Promise<ProviderTurnStartResult>;+ readonly interruptTurn: (sessionId: ProviderSessionId, turnId?: ProviderTurnId) => Promise<void>;+ readonly readThread: (sessionId: ProviderSessionId) => Promise<ProviderThreadSnapshot>;+ readonly rollbackThread: (+ sessionId: ProviderSessionId,+ numTurns: number,+ ) => Promise<ProviderThreadSnapshot>;+ readonly respondToRequest: (+ sessionId: ProviderSessionId,+ requestId: ApprovalRequestId,+ decision: ProviderApprovalDecision,+ ) => Promise<void>;+ readonly stopSession: (sessionId: ProviderSessionId) => void;+ readonly listSessions: () => ReadonlyArray<ProviderSession>;+ readonly hasSession: (sessionId: ProviderSessionId) => boolean;+ readonly stopAll: () => void;+ readonly streamEvents: Stream.Stream<ProviderRuntimeEvent>;+}++export interface ClaudeCodeAdapterLiveOptions {+ readonly runtime?: ClaudeCodeRuntime;+ readonly makeRuntime?: () => ClaudeCodeRuntime;+}++function toMessage(cause: unknown, fallback: string): string {+ if (cause instanceof Error && cause.message.length > 0) {+ return cause.message;+ }+ return fallback;+}++function toSessionError(+ sessionId: ProviderSessionId,+ cause: unknown,+): ProviderAdapterSessionNotFoundError | ProviderAdapterSessionClosedError | undefined {+ const normalized = toMessage(cause, "").toLowerCase();+ if (normalized.includes("unknown session") || normalized.includes("unknown provider session")) {+ return new ProviderAdapterSessionNotFoundError({+ provider: PROVIDER,+ sessionId,+ cause,+ });+ }+ if (normalized.includes("session is closed")) {+ return new ProviderAdapterSessionClosedError({+ provider: PROVIDER,+ sessionId,+ cause,+ });+ }+ return undefined;+}++function toRequestError(+ sessionId: ProviderSessionId,+ method: string,+ cause: unknown,+): ProviderAdapterError {+ const sessionError = toSessionError(sessionId, cause);+ if (sessionError) {+ return sessionError;+ }+ return new ProviderAdapterRequestError({+ provider: PROVIDER,+ method,+ detail: toMessage(cause, `${method} failed`),+ cause,+ });+}++function makeUnavailableRuntime(): ClaudeCodeRuntime {+ const unavailable = async (): Promise<never> => {+ throw new Error("Claude Code runtime is not configured.");+ };++ return {+ startSession: unavailable,+ sendTurn: unavailable,+ interruptTurn: unavailable,+ readThread: unavailable,+ rollbackThread: unavailable,+ respondToRequest: unavailable,+ stopSession: () => {},+ listSessions: () => [],+ hasSession: () => false,+ stopAll: () => {},+ streamEvents: Stream.empty,+ };+}++const makeClaudeCodeAdapter = (options?: ClaudeCodeAdapterLiveOptions) =>+ Effect.gen(function* () {+ const runtime = yield* Effect.acquireRelease(+ Effect.sync(() => {+ if (options?.runtime) {+ return options.runtime;+ }+ if (options?.makeRuntime) {+ return options.makeRuntime();+ }+ return makeUnavailableRuntime();+ }),+ (runtime) =>+ Effect.sync(() => {+ try {+ runtime.stopAll();+ } catch {+ // Finalizers should never fail and block shutdown.+ }+ }),+ );++ const startSession: ClaudeCodeAdapterShape["startSession"] = (input) => {+ if (input.provider !== undefined && input.provider !== PROVIDER) {+ return Effect.fail(+ new ProviderAdapterValidationError({+ provider: PROVIDER,+ operation: "startSession",+ issue: `Expected provider '${PROVIDER}' but received '${input.provider}'.`,+ }),+ );+ }++ return Effect.tryPromise({+ try: () => runtime.startSession(input),+ catch: (cause) =>+ new ProviderAdapterProcessError({+ provider: PROVIDER,+ sessionId: "pending",+ detail: toMessage(cause, "Failed to start Claude Code adapter session."),+ cause,+ }),+ });+ };++ const sendTurn: ClaudeCodeAdapterShape["sendTurn"] = (input) =>+ Effect.tryPromise({+ try: () => runtime.sendTurn(input),+ catch: (cause) => toRequestError(input.sessionId, "turn/start", cause),+ });++ const interruptTurn: ClaudeCodeAdapterShape["interruptTurn"] = (sessionId, turnId) =>+ Effect.tryPromise({+ try: () => runtime.interruptTurn(sessionId, turnId),+ catch: (cause) => toRequestError(sessionId, "turn/interrupt", cause),+ });++ const readThread: ClaudeCodeAdapterShape["readThread"] = (sessionId) =>+ Effect.tryPromise({+ try: () => runtime.readThread(sessionId),+ catch: (cause) => toRequestError(sessionId, "thread/read", cause),+ });++ const rollbackThread: ClaudeCodeAdapterShape["rollbackThread"] = (sessionId, numTurns) => {+ if (!Number.isInteger(numTurns) || numTurns < 1) {+ return Effect.fail(+ new ProviderAdapterValidationError({+ provider: PROVIDER,+ operation: "rollbackThread",+ issue: "numTurns must be an integer >= 1.",+ }),+ );+ }++ return Effect.tryPromise({+ try: () => runtime.rollbackThread(sessionId, numTurns),+ catch: (cause) => toRequestError(sessionId, "thread/rollback", cause),+ });+ };++ const respondToRequest: ClaudeCodeAdapterShape["respondToRequest"] = (+ sessionId,+ requestId,+ decision,+ ) =>+ Effect.tryPromise({+ try: () => runtime.respondToRequest(sessionId, requestId, decision),+ catch: (cause) => toRequestError(sessionId, "item/requestApproval/decision", cause),+ });++ const stopSession: ClaudeCodeAdapterShape["stopSession"] = (sessionId) =>+ Effect.sync(() => {+ runtime.stopSession(sessionId);+ });++ const listSessions: ClaudeCodeAdapterShape["listSessions"] = () =>+ Effect.sync(() => runtime.listSessions());++ const hasSession: ClaudeCodeAdapterShape["hasSession"] = (sessionId) =>+ Effect.sync(() => runtime.hasSession(sessionId));++ const stopAll: ClaudeCodeAdapterShape["stopAll"] = () =>+ Effect.sync(() => {+ runtime.stopAll();+ });++ return {+ provider: PROVIDER,+ startSession,+ sendTurn,+ interruptTurn,+ readThread,+ rollbackThread,+ respondToRequest,+ stopSession,+ listSessions,+ hasSession,+ stopAll,+ streamEvents: runtime.streamEvents,+ } satisfies ClaudeCodeAdapterShape;+ });++export const ClaudeCodeAdapterLive = Layer.effect(ClaudeCodeAdapter, makeClaudeCodeAdapter());++export function makeClaudeCodeAdapterLive(options?: ClaudeCodeAdapterLiveOptions) {+ return Layer.effect(ClaudeCodeAdapter, makeClaudeCodeAdapter(options));+}+diff --git a/apps/server/src/provider/Services/ClaudeCodeAdapter.ts b/apps/server/src/provider/Services/ClaudeCodeAdapter.tsnew file mode 100644index 000000000..80fb8771d--- /dev/null+++ b/apps/server/src/provider/Services/ClaudeCodeAdapter.ts@@ -0,0 +1,32 @@+/**+ * ClaudeCodeAdapter - Claude Code implementation of the generic provider adapter contract.+ *+ * This service owns Claude runtime/session semantics and emits canonical+ * provider runtime events. It does not perform cross-provider routing, shared+ * event fan-out, or checkpoint orchestration.+ *+ * Uses Effect `ServiceMap.Service` for dependency injection and returns the+ * shared provider-adapter error channel with `provider: "claudeCode"` context.+ *+ * @module ClaudeCodeAdapter+ */+import { ServiceMap } from "effect";++import type { ProviderAdapterError } from "../Errors.ts";+import type { ProviderAdapterShape } from "./ProviderAdapter.ts";++/**+ * ClaudeCodeAdapterShape - Service API for the Claude Code provider adapter.+ */+export interface ClaudeCodeAdapterShape extends ProviderAdapterShape<ProviderAdapterError> {+ readonly provider: "claudeCode";+}++/**+ * ClaudeCodeAdapter - Service tag for Claude Code provider adapter operations.+ */+export class ClaudeCodeAdapter extends ServiceMap.Service<+ ClaudeCodeAdapter,+ ClaudeCodeAdapterShape+>()("t3/provider/Services/ClaudeCodeAdapter") {}+