@hellcoder/companion 0.113.4 → 0.113.5-preview.20260730100656.ecb60c9

package/server/claude-sdk-adapter.ts

@@ -0,0 +1,394 @@
+/**
+ * SdkClaudeAdapter — the Claude Code transport built on the official
+ * `@anthropic-ai/claude-agent-sdk` instead of a hand-rolled stdio bridge.
+ *
+ * Why this exists: the stdio transport in `ClaudeAdapter` reverse-engineers
+ * the CLI's stream-json protocol and owns raw process lifecycle, which is
+ * where every transport-level failure this project has debugged lived
+ * (spurious stdout EOFs, wedge-kill heuristics, handshake drift across CLI
+ * versions). The Agent SDK is Anthropic's maintained implementation of the
+ * same protocol: it spawns the same `claude` binary, uses the same
+ * subscription credentials, and tracks CLI protocol changes upstream.
+ *
+ * Design: this class REUSES ClaudeAdapter's entire message brain — routing
+ * (`handleRawMessage`), outbound translation (`send` → `handleOutgoing*` →
+ * `sendRaw`), recording, and pre-connect queueing — and swaps only the byte
+ * transport:
+ *
+ *   inbound:  SDK async-generator messages → JSON.stringify → handleRawMessage
+ *   outbound: sendRaw override parses the NDJSON the base class built and
+ *             dispatches it to the SDK (input stream / Query control methods)
+ *
+ * Because the SDK's message objects ARE the CLI's stream-json frames, the
+ * bridge and frontend see byte-identical traffic to the stdio transport.
+ *
+ * Selection is per spawn: `settings.claudeTransport === "sdk"` (see
+ * cli-launcher). Switching the setting and hitting Reconnect migrates a live
+ * session between transports via `--resume`.
+ */
+import { randomUUID } from "node:crypto";
+import {
+  query,
+  type Options as SdkOptions,
+  type PermissionMode,
+  type PermissionResult,
+  type PermissionUpdate,
+  type Query,
+  type SDKUserMessage,
+} from "@anthropic-ai/claude-agent-sdk";
+import { ClaudeAdapter } from "./claude-adapter.js";
+import { log } from "./logger.js";
+
+export interface SdkAttachOptions {
+  model?: string;
+  permissionMode?: string;
+  /** Reasoning-effort level (low|medium|high|xhigh|max). */
+  effort?: string;
+  cwd?: string;
+  /** Claude-internal session id to resume. */
+  resume?: string;
+  /** Resume only up to this message UUID (fork points). */
+  resumeSessionAt?: string;
+  /** Fork to a new session id instead of continuing `resume`. */
+  forkSession?: boolean;
+  env?: Record<string, string>;
+  /** Path to the installed `claude` binary, so the SDK drives the same
+   *  logged-in CLI (and the same subscription auth) as the stdio transport. */
+  claudeBinary?: string;
+}
+
+/** Minimal async queue that adapts push-style sends to the SDK's
+ *  pull-style AsyncIterable input. */
+class AsyncMessageQueue<T> implements AsyncIterable<T> {
+  private buffer: T[] = [];
+  private waiters: Array<(r: IteratorResult<T>) => void> = [];
+  private closed = false;
+
+  push(item: T): void {
+    if (this.closed) return;
+    const waiter = this.waiters.shift();
+    if (waiter) waiter({ value: item, done: false });
+    else this.buffer.push(item);
+  }
+
+  close(): void {
+    this.closed = true;
+    for (const waiter of this.waiters.splice(0)) {
+      waiter({ value: undefined as never, done: true });
+    }
+  }
+
+  [Symbol.asyncIterator](): AsyncIterator<T> {
+    return {
+      next: (): Promise<IteratorResult<T>> => {
+        if (this.buffer.length > 0) {
+          return Promise.resolve({ value: this.buffer.shift() as T, done: false });
+        }
+        if (this.closed) {
+          return Promise.resolve({ value: undefined as never, done: true });
+        }
+        return new Promise((resolve) => this.waiters.push(resolve));
+      },
+    };
+  }
+}
+
+export class SdkClaudeAdapter extends ClaudeAdapter {
+  private sdkQuery: Query | null = null;
+  private inputQueue = new AsyncMessageQueue<SDKUserMessage>();
+  private abortController = new AbortController();
+  private sdkActive = false;
+  /** Pending canUseTool resolvers keyed by the synthetic request_id shown to the bridge. */
+  private pendingPermissionResolvers = new Map<string, (r: PermissionResult) => void>();
+  private exitCb: ((code: number | null) => void) | null = null;
+  /** Collects the CLI's stderr (via the SDK callback) for exit classification. */
+  private stderrSink: ((data: string) => void) | null = null;
+
+  constructor(
+    sessionId: string,
+    opts?: ConstructorParameters<typeof ClaudeAdapter>[1] & {
+      onStderr?: (data: string) => void;
+    },
+  ) {
+    super(sessionId, opts);
+    this.stderrSink = opts?.onStderr ?? null;
+  }
+
+  /** Launcher registers this to mirror the stdio path's `proc.exited` handling. */
+  onExit(cb: (code: number | null) => void): void {
+    this.exitCb = cb;
+  }
+
+  /** Hard-stop the underlying CLI (the SDK terminates its child process). */
+  abort(): void {
+    this.abortController.abort();
+    this.inputQueue.close();
+  }
+
+  attachSdk(options: SdkAttachOptions): void {
+    this.transportKind = "sdk";
+    this.sdkActive = true;
+
+    const sdkOptions: SdkOptions = {
+      abortController: this.abortController,
+      includePartialMessages: true,
+      ...(options.model ? { model: options.model } : {}),
+      ...(options.permissionMode
+        ? { permissionMode: options.permissionMode as PermissionMode }
+        : {}),
+      ...(options.effort ? { effort: options.effort as SdkOptions["effort"] } : {}),
+      ...(options.cwd ? { cwd: options.cwd } : {}),
+      ...(options.resume ? { resume: options.resume } : {}),
+      ...(options.resumeSessionAt ? { resumeSessionAt: options.resumeSessionAt } : {}),
+      ...(options.forkSession ? { forkSession: true } : {}),
+      ...(options.claudeBinary ? { pathToClaudeCodeExecutable: options.claudeBinary } : {}),
+      // Preserve the full server environment: the CLI resolves subscription
+      // OAuth credentials itself, exactly like the stdio transport. (Do NOT
+      // inject ANTHROPIC_API_KEY here — it would silently switch sessions
+      // from subscription windows to metered API billing.)
+      env: { ...(process.env as Record<string, string>), ...(options.env ?? {}) },
+      stderr: (data: string) => this.stderrSink?.(data),
+      canUseTool: (toolName, input, cbOptions) =>
+        this.handleCanUseTool(toolName, input, cbOptions),
+    };
+
+    this.sdkQuery = query({ prompt: this.inputQueue, options: sdkOptions });
+    void this.pumpMessages(this.sdkQuery);
+
+    // Flush anything the bridge queued before the transport attached.
+    for (const ndjson of this.pendingMessages.splice(0)) {
+      this.sendRaw(ndjson);
+    }
+  }
+
+  /** Route every SDK message through the same brain as CLI stdout lines. */
+  private async pumpMessages(q: Query): Promise<void> {
+    let exitCode: number | null = 0;
+    try {
+      for await (const message of q) {
+        this.handleRawMessage(JSON.stringify(message));
+      }
+    } catch (err) {
+      if (this.abortController.signal.aborted) {
+        // Intentional kill (launcher/relaunch): report like a SIGTERM'd child.
+        exitCode = 143;
+      } else {
+        exitCode = 1;
+        log.error("claude-sdk-adapter", "SDK query terminated with error", {
+          sessionId: this.sessionId,
+          error: err instanceof Error ? err.message : String(err),
+        });
+      }
+    } finally {
+      this.sdkActive = false;
+      this.sdkQuery = null;
+      this.inputQueue.close();
+      for (const resolve of this.pendingPermissionResolvers.values()) {
+        resolve({ behavior: "deny", message: "Session ended" });
+      }
+      this.pendingPermissionResolvers.clear();
+      // Same single-shot disconnect contract as the stdio transport.
+      if (!this.disconnectFired) {
+        this.disconnectFired = true;
+        this.disconnectCb?.();
+      }
+      this.exitCb?.(exitCode);
+    }
+  }
+
+  // ── Permissions: SDK callback ⇆ existing bridge round-trip ────────────────
+
+  /**
+   * The SDK surfaces permission prompts as a callback instead of raw
+   * `can_use_tool` control_request frames. Re-synthesize the frame the CLI
+   * would have sent so the bridge's permission UI, AI validation, and
+   * cancellation flows run unchanged; the bridge's eventual
+   * `control_response` is intercepted in `sendRaw` and resolves the callback.
+   */
+  private handleCanUseTool(
+    toolName: string,
+    input: Record<string, unknown>,
+    cbOptions: {
+      signal: AbortSignal;
+      suggestions?: PermissionUpdate[];
+      blockedPath?: string;
+      decisionReason?: unknown;
+      title?: string;
+      tool_use_id?: string;
+    },
+  ): Promise<PermissionResult> {
+    const requestId = `sdkperm-${randomUUID()}`;
+    return new Promise<PermissionResult>((resolve) => {
+      this.pendingPermissionResolvers.set(requestId, resolve);
+
+      cbOptions.signal.addEventListener("abort", () => {
+        if (!this.pendingPermissionResolvers.delete(requestId)) return;
+        // Mirror the CLI's cancel frame so the bridge clears its pending UI.
+        this.handleRawMessage(
+          JSON.stringify({ type: "control_cancel_request", request_id: requestId }),
+        );
+        resolve({ behavior: "deny", message: "Request cancelled" });
+      });
+
+      this.handleRawMessage(
+        JSON.stringify({
+          type: "control_request",
+          request_id: requestId,
+          request: {
+            subtype: "can_use_tool",
+            tool_name: toolName,
+            input,
+            permission_suggestions: cbOptions.suggestions,
+            blocked_path: cbOptions.blockedPath,
+            decision_reason: cbOptions.decisionReason,
+            title: cbOptions.title,
+            tool_use_id: cbOptions.tool_use_id,
+          },
+        }),
+      );
+    });
+  }
+
+  // ── Transport overrides ───────────────────────────────────────────────────
+
+  isConnected(): boolean {
+    return this.sdkActive;
+  }
+
+  async disconnect(): Promise<void> {
+    // Mirrors the stdio contract: mark the transport gone; the launcher owns
+    // the hard kill (abort()). Closing the input stream lets the CLI finish
+    // its current turn and exit cleanly.
+    this.sdkActive = false;
+    this.inputQueue.close();
+  }
+
+  /**
+   * The base class hands every outbound frame here as NDJSON. Parse it back
+   * and dispatch to the SDK: user messages into the input stream, control
+   * requests onto the Query's control methods, and permission
+   * control_responses into the pending canUseTool resolvers.
+   */
+  protected sendRaw(ndjson: string): boolean {
+    this.recorder?.record(this.sessionId, "out", ndjson, "cli", "claude", "");
+
+    let msg: Record<string, unknown>;
+    try {
+      msg = JSON.parse(ndjson) as Record<string, unknown>;
+    } catch {
+      return false;
+    }
+
+    switch (msg.type) {
+      case "user": {
+        const m = msg as unknown as { message: SDKUserMessage["message"]; parent_tool_use_id?: string | null };
+        this.inputQueue.push({
+          type: "user",
+          message: m.message,
+          parent_tool_use_id: m.parent_tool_use_id ?? null,
+        } as SDKUserMessage);
+        return true;
+      }
+
+      case "control_response":
+        return this.resolvePermissionFromControlResponse(msg);
+
+      case "control_request":
+        return this.dispatchControlRequest(msg);
+
+      default:
+        log.warn("claude-sdk-adapter", "Unsupported outbound frame for SDK transport; dropped", {
+          sessionId: this.sessionId,
+          frameType: String(msg.type),
+        });
+        return false;
+    }
+  }
+
+  private resolvePermissionFromControlResponse(msg: Record<string, unknown>): boolean {
+    const response = (msg as {
+      response?: { request_id?: string; response?: Record<string, unknown> };
+    }).response;
+    const requestId = response?.request_id;
+    if (!requestId) return false;
+    const resolve = this.pendingPermissionResolvers.get(requestId);
+    if (!resolve) {
+      // Not a permission reply we own (e.g. a stray late response) — ignore.
+      return true;
+    }
+    this.pendingPermissionResolvers.delete(requestId);
+    const inner = response?.response ?? {};
+    if (inner.behavior === "allow") {
+      resolve({
+        behavior: "allow",
+        updatedInput: (inner.updatedInput as Record<string, unknown>) ?? {},
+        ...(Array.isArray(inner.updatedPermissions) && inner.updatedPermissions.length
+          ? { updatedPermissions: inner.updatedPermissions as PermissionUpdate[] }
+          : {}),
+      });
+    } else {
+      resolve({
+        behavior: "deny",
+        message: typeof inner.message === "string" ? inner.message : "Denied by user",
+      });
+    }
+    return true;
+  }
+
+  /** Map the CLI control protocol onto the SDK Query's methods. */
+  private dispatchControlRequest(msg: Record<string, unknown>): boolean {
+    const requestId = String(msg.request_id ?? "");
+    const request = (msg.request ?? {}) as Record<string, unknown>;
+    const subtype = String(request.subtype ?? "");
+    const q = this.sdkQuery;
+    if (!q) return false;
+
+    const respond = (payload: Record<string, unknown> = {}) => {
+      this.handleRawMessage(
+        JSON.stringify({
+          type: "control_response",
+          response: { subtype: "success", request_id: requestId, response: payload },
+        }),
+      );
+    };
+    const respondError = (error: string) => {
+      this.handleRawMessage(
+        JSON.stringify({
+          type: "control_response",
+          response: { subtype: "error", request_id: requestId, error },
+        }),
+      );
+    };
+
+    switch (subtype) {
+      case "interrupt":
+        q.interrupt().then(() => respond()).catch((e) => respondError(String(e)));
+        return true;
+      case "set_model":
+        q.setModel(request.model as string | undefined)
+          .then(() => respond())
+          .catch((e) => respondError(String(e)));
+        return true;
+      case "set_permission_mode":
+        q.setPermissionMode(request.mode as PermissionMode)
+          .then(() => respond())
+          .catch((e) => respondError(String(e)));
+        return true;
+      case "mcp_status":
+        q.mcpServerStatus()
+          .then((servers) => respond({ mcpServers: servers }))
+          .catch((e) => respondError(String(e)));
+        return true;
+      case "end_session":
+        // Graceful shutdown: stop feeding input; the CLI ends on its own.
+        this.inputQueue.close();
+        respond();
+        return true;
+      default:
+        // Honest failure beats silent drop: the bridge's resolver (if any)
+        // gets an error response instead of timing out.
+        respondError(`Control subtype "${subtype}" is not supported by the SDK transport`);
+        return true;
+    }
+  }
+}

package/server/cli-launcher.ts

@@ -15,6 +15,8 @@ import { looksLikeAuthErrorText } from "./session-types.js";
 import type { RecorderManager } from "./recorder.js";
 import { CodexAdapter } from "./codex-adapter.js";
 import { ClaudeAdapter } from "./claude-adapter.js";
+import { SdkClaudeAdapter } from "./claude-sdk-adapter.js";
+import { getSettings } from "./settings-manager.js";
 import { resolveBinary, getEnrichedPath } from "./path-resolver.js";
 import { containerManager } from "./container-manager.js";
 import { companionBus } from "./event-bus.js";
@@ -204,6 +206,10 @@ export class CliLauncher {
    */
   private stderrTails = new Map<string, string>();
   private static readonly STDERR_TAIL_MAX = 4096;
+  /** Active SDK-transport adapters (settings.claudeTransport === "sdk"). The
+   *  SDK owns the child process, so these sessions have no entry in
+   *  `this.processes`; kill/relaunch go through the adapter's abort(). */
+  private sdkAdapters = new Map<string, SdkClaudeAdapter>();
   private store: SessionStore | null = null;
   private recorder: RecorderManager | null = null;
 
@@ -371,6 +377,13 @@ export class CliLauncher {
     // WS session exit handler, which clears `this.processes`.
     const oldProc = this.processes.get(sessionId);
     const oldProxy = this.codexWsProxies.get(sessionId);
+    const oldSdk = this.sdkAdapters.get(sessionId);
+    if (oldSdk) {
+      // Abort tears down the SDK's child; safe to respawn immediately since
+      // the new session resumes by id, not by pipe.
+      try { oldSdk.abort(); } catch {}
+      this.sdkAdapters.delete(sessionId);
+    }
     if (oldProxy) {
       try {
         oldProxy.kill("SIGTERM");
@@ -483,6 +496,81 @@ export class CliLauncher {
     return Array.from(this.sessions.values()).filter((s) => s.state === "starting");
   }
 
+  /**
+   * Launch a Claude session over the official Agent SDK (claude-sdk-adapter).
+   * Mirrors the stdio path's contract: same adapter-created event, same
+   * session:exited emission (driving proactive keepalive relaunch), same
+   * stderr-tail capture for exit classification. The SDK owns the subprocess,
+   * so there is no `this.processes` entry and no PID-based liveness.
+   */
+  private spawnSdk(
+    sessionId: string,
+    info: SdkSessionInfo,
+    options: LaunchOptions & { resumeSessionId?: string },
+    binary: string,
+  ): void {
+    console.log(
+      `[cli-launcher] Spawning session ${sessionId} via Agent SDK transport` +
+      `${options.resumeSessionId ? ` (resume ${options.resumeSessionId})` : ""}`,
+    );
+
+    const adapter = new SdkClaudeAdapter(sessionId, {
+      recorder: this.recorder ?? undefined,
+      cwd: info.cwd,
+      getStderrTail: () => this.stderrTails.get(sessionId) ?? "",
+      onStderr: (text: string) => {
+        if (!text) return;
+        const merged = (this.stderrTails.get(sessionId) ?? "") + text;
+        this.stderrTails.set(
+          sessionId,
+          merged.length > CliLauncher.STDERR_TAIL_MAX
+            ? merged.slice(-CliLauncher.STDERR_TAIL_MAX)
+            : merged,
+        );
+      },
+    });
+
+    const spawnedAt = Date.now();
+    adapter.onExit((exitCode) => {
+      console.log(`[cli-launcher] Session ${sessionId} exited (code=${exitCode}) [sdk transport]`);
+      const session = this.sessions.get(sessionId);
+      if (session) {
+        session.state = "exited";
+        session.exitCode = exitCode ?? -1;
+        // Immediate death after resume ⇒ the resume likely failed; start fresh
+        // next time. Same heuristic as the stdio path.
+        const uptime = Date.now() - spawnedAt;
+        if (uptime < 5000 && options.resumeSessionId) {
+          console.error(`[cli-launcher] Session ${sessionId} exited immediately after SDK resume (${uptime}ms). Clearing cliSessionId for fresh start.`);
+          session.cliSessionId = undefined;
+        }
+      }
+      this.sdkAdapters.delete(sessionId);
+      this.persistState();
+      const reason = this.classifyExitReason(sessionId, exitCode ?? -1);
+      this.stderrTails.delete(sessionId);
+      companionBus.emit("session:exited", { sessionId, exitCode: exitCode ?? -1, reason });
+    });
+
+    adapter.attachSdk({
+      model: options.model,
+      permissionMode: options.permissionMode,
+      effort: options.effort,
+      cwd: info.cwd,
+      resume: options.resumeSessionId,
+      resumeSessionAt: options.resumeSessionAt,
+      forkSession: options.forkSession,
+      env: options.env,
+      claudeBinary: binary,
+    });
+
+    this.sdkAdapters.set(sessionId, adapter);
+    companionBus.emit("backend:claude-adapter-created", { sessionId, adapter });
+    info.state = "connected";
+    info.pid = undefined;
+    this.persistState();
+  }
+
   private spawnCLI(sessionId: string, info: SdkSessionInfo, options: LaunchOptions & { resumeSessionId?: string }): void {
     const isContainerized = !!options.containerId;
 
@@ -502,6 +590,15 @@ export class CliLauncher {
       }
     }
 
+    // Experimental switchable transport: run this session through the official
+    // Agent SDK instead of the hand-rolled stdio bridge. Chosen at spawn time,
+    // so flipping the setting + Reconnect migrates a session via --resume.
+    // Containerized sessions always use stdio (the SDK cannot docker-exec).
+    if (!isContainerized && getSettings().claudeTransport === "sdk") {
+      this.spawnSdk(sessionId, info, options, binary);
+      return;
+    }
+
     let effectivePermissionMode = options.permissionMode;
     const shouldDowngradeContainerBypass =
       isContainerized
@@ -1188,6 +1285,19 @@ export class CliLauncher {
    * Kill a session's CLI process.
    */
   async kill(sessionId: string): Promise<boolean> {
+    const sdkAdapter = this.sdkAdapters.get(sessionId);
+    if (sdkAdapter) {
+      // The SDK terminates its child on abort; onExit fires the shared
+      // session:exited handling.
+      sdkAdapter.abort();
+      this.sdkAdapters.delete(sessionId);
+      const sdkSession = this.sessions.get(sessionId);
+      if (sdkSession) {
+        sdkSession.state = "exited";
+      }
+      this.persistState();
+      return true;
+    }
     const proxy = this.codexWsProxies.get(sessionId);
     if (proxy) {
       try { proxy.kill("SIGTERM"); } catch {}

package/server/routes/settings-routes.ts

@@ -37,6 +37,7 @@ export function registerSettingsRoutes(api: Hono): void {
       keepaliveDetachedSessions: settings.keepaliveDetachedSessions,
       wedgeKillEnabled: settings.wedgeKillEnabled,
       silenceProbeEnabled: settings.silenceProbeEnabled,
+      claudeTransport: settings.claudeTransport ?? "stdio",
       cliBridgeMode: settings.cliBridgeMode,
     });
   });
@@ -144,6 +145,9 @@ export function registerSettingsRoutes(api: Hono): void {
     if (body.silenceProbeEnabled !== undefined && typeof body.silenceProbeEnabled !== "boolean") {
       return c.json({ error: "silenceProbeEnabled must be a boolean" }, 400);
     }
+    if (body.claudeTransport !== undefined && body.claudeTransport !== "stdio" && body.claudeTransport !== "sdk") {
+      return c.json({ error: 'claudeTransport must be "stdio" or "sdk"' }, 400);
+    }
     if (body.cliBridgeMode !== undefined && body.cliBridgeMode !== "loopback" && body.cliBridgeMode !== "jsonHandoff") {
       return c.json({ error: "cliBridgeMode must be 'loopback' or 'jsonHandoff'" }, 400);
     }
@@ -167,6 +171,7 @@ export function registerSettingsRoutes(api: Hono): void {
       || body.keepaliveDetachedSessions !== undefined
       || body.wedgeKillEnabled !== undefined
       || body.silenceProbeEnabled !== undefined
+      || body.claudeTransport !== undefined
       || body.cliBridgeMode !== undefined;
     if (!hasAnyField) {
       return c.json({ error: "At least one settings field is required" }, 400);
@@ -293,6 +298,10 @@ export function registerSettingsRoutes(api: Hono): void {
         typeof body.silenceProbeEnabled === "boolean"
           ? body.silenceProbeEnabled
           : undefined,
+      claudeTransport:
+        body.claudeTransport === "stdio" || body.claudeTransport === "sdk"
+          ? (body.claudeTransport as "stdio" | "sdk")
+          : undefined,
       cliBridgeMode:
         body.cliBridgeMode === "loopback" || body.cliBridgeMode === "jsonHandoff"
           ? (body.cliBridgeMode as CliBridgeMode)
@@ -329,6 +338,7 @@ export function registerSettingsRoutes(api: Hono): void {
       keepaliveDetachedSessions: settings.keepaliveDetachedSessions,
       wedgeKillEnabled: settings.wedgeKillEnabled,
       silenceProbeEnabled: settings.silenceProbeEnabled,
+      claudeTransport: settings.claudeTransport ?? "stdio",
       cliBridgeMode: settings.cliBridgeMode,
     });
   });