@hellcoder/companion 0.116.0 → 0.116.1-preview.20260814041931.d191f06

package/server/message-extract.ts

@@ -0,0 +1,79 @@
+// ─── Shared BrowserIncomingMessage extraction helpers ────────────────────────
+//
+// Pure functions for pulling text / tool activity out of the bridge's
+// message stream. Used by consumers that tap companionBus message events
+// (linear-agent-bridge, magic-ui-watcher).
+
+import type { BrowserIncomingMessage } from "./session-types.js";
+
+/** Content blocks of an assistant message, or null. */
+export function getAssistantContent(msg: BrowserIncomingMessage): unknown[] | null {
+  if (msg.type !== "assistant") return null;
+  // Assistant messages carry content blocks at msg.message.content
+  const raw = msg as Record<string, unknown>;
+  const message = raw.message;
+  if (!message || typeof message !== "object") return null;
+  const content = (message as Record<string, unknown>).content;
+  return Array.isArray(content) ? content : null;
+}
+
+/** Extract text from assistant message content blocks */
+export function extractTextFromAssistant(msg: BrowserIncomingMessage): string {
+  const content = getAssistantContent(msg);
+  if (!content) return "";
+  return content
+    .filter((b): b is { type: string; text: string } =>
+      typeof b === "object" && b !== null && (b as Record<string, unknown>).type === "text" && typeof (b as Record<string, unknown>).text === "string")
+    .map((b) => b.text)
+    .join("\n");
+}
+
+/** Extract text deltas from stream events. */
+export function extractTextDeltaFromStreamEvent(msg: BrowserIncomingMessage): string {
+  if (msg.type !== "stream_event") return "";
+  const event = msg.event as Record<string, unknown> | undefined;
+  if (!event || event.type !== "content_block_delta") return "";
+  const delta = event.delta as Record<string, unknown> | undefined;
+  if (!delta || delta.type !== "text_delta" || typeof delta.text !== "string") return "";
+  return delta.text;
+}
+
+/** Extract all tool use blocks from assistant message content (with raw input for plan extraction) */
+export function extractToolUses(msg: BrowserIncomingMessage): Array<{ id?: string; name: string; input: string; rawInput?: Record<string, unknown> }> {
+  const content = getAssistantContent(msg);
+  if (!content) return [];
+  return content
+    .filter((b): b is { type: string; id?: string; name: string; input?: Record<string, unknown> } =>
+      typeof b === "object" && b !== null
+      && (b as Record<string, unknown>).type === "tool_use"
+      && typeof (b as Record<string, unknown>).name === "string")
+    .map((toolBlock) => ({
+      id: typeof toolBlock.id === "string" ? toolBlock.id : undefined,
+      name: toolBlock.name,
+      input: toolBlock.input ? JSON.stringify(toolBlock.input).slice(0, 200) : "",
+      rawInput: toolBlock.input,
+    }));
+}
+
+/** Extract tool_result blocks from assistant message content. */
+export function extractToolResults(msg: BrowserIncomingMessage): Array<{ tool_use_id: string; content: string }> {
+  const content = getAssistantContent(msg);
+  if (!content) return [];
+  return content
+    .filter((b): b is { type: string; tool_use_id: string; content?: unknown } =>
+      typeof b === "object" && b !== null
+      && (b as Record<string, unknown>).type === "tool_result"
+      && typeof (b as Record<string, unknown>).tool_use_id === "string")
+    .map((block) => ({
+      tool_use_id: block.tool_use_id,
+      content: typeof block.content === "string"
+        ? block.content.slice(0, 500)
+        : Array.isArray(block.content)
+          ? (block.content as Array<{ type?: string; text?: string }>)
+            .filter((c) => c.type === "text" && typeof c.text === "string")
+            .map((c) => c.text)
+            .join("\n")
+            .slice(0, 500)
+          : "",
+    }));
+}

package/server/routes/settings-routes.ts

@@ -3,6 +3,7 @@ import { DASHBOARD_MODEL_OPTIONS, DEFAULT_ANTHROPIC_MODEL, getSettings, updateSe
 import { linearCache } from "../linear-cache.js";
 import { listConnections } from "../linear-connections.js";
 import { hasContainerCodexAuth } from "../codex-container-auth.js";
+import { isClaudeCliAvailable } from "../claude-cli-runner.js";
 
 export function registerSettingsRoutes(api: Hono): void {
   api.get("/settings", (c) => {
@@ -30,6 +31,9 @@ export function registerSettingsRoutes(api: Hono): void {
       dashboardModel: settings.dashboardModel,
       dashboardRunHour: settings.dashboardRunHour,
       dashboardMaxSessionsPerRun: settings.dashboardMaxSessionsPerRun,
+      magicUiEnabled: settings.magicUiEnabled,
+      magicUiModel: settings.magicUiModel,
+      claudeCliAvailable: isClaudeCliAvailable(),
       publicUrl: settings.publicUrl,
       updateChannel: settings.updateChannel,
       dockerAutoUpdate: settings.dockerAutoUpdate,
@@ -100,6 +104,12 @@ export function registerSettingsRoutes(api: Hono): void {
     ) {
       return c.json({ error: "dashboardMaxSessionsPerRun must be an integer between 1 and 200" }, 400);
     }
+    if (body.magicUiEnabled !== undefined && typeof body.magicUiEnabled !== "boolean") {
+      return c.json({ error: "magicUiEnabled must be a boolean" }, 400);
+    }
+    if (body.magicUiModel !== undefined && !DASHBOARD_MODEL_OPTIONS.includes(body.magicUiModel)) {
+      return c.json({ error: `magicUiModel must be one of: ${DASHBOARD_MODEL_OPTIONS.join(", ")}` }, 400);
+    }
     if (body.publicUrl !== undefined) {
       if (typeof body.publicUrl !== "string") {
         return c.json({ error: "publicUrl must be a string" }, 400);
@@ -164,6 +174,7 @@ export function registerSettingsRoutes(api: Hono): void {
       || body.aiValidationAutoDeny !== undefined
       || body.dashboardEnabled !== undefined || body.dashboardModel !== undefined
       || body.dashboardRunHour !== undefined || body.dashboardMaxSessionsPerRun !== undefined
+      || body.magicUiEnabled !== undefined || body.magicUiModel !== undefined
       || body.publicUrl !== undefined
       || body.updateChannel !== undefined
       || body.dockerAutoUpdate !== undefined
@@ -270,6 +281,14 @@ export function registerSettingsRoutes(api: Hono): void {
         typeof body.dashboardMaxSessionsPerRun === "number"
           ? body.dashboardMaxSessionsPerRun
           : undefined,
+      magicUiEnabled:
+        typeof body.magicUiEnabled === "boolean"
+          ? body.magicUiEnabled
+          : undefined,
+      magicUiModel:
+        typeof body.magicUiModel === "string"
+          ? body.magicUiModel
+          : undefined,
       publicUrl:
         typeof body.publicUrl === "string"
           ? body.publicUrl.trim().replace(/\/+$/, "")
@@ -331,6 +350,9 @@ export function registerSettingsRoutes(api: Hono): void {
       dashboardModel: settings.dashboardModel,
       dashboardRunHour: settings.dashboardRunHour,
       dashboardMaxSessionsPerRun: settings.dashboardMaxSessionsPerRun,
+      magicUiEnabled: settings.magicUiEnabled,
+      magicUiModel: settings.magicUiModel,
+      claudeCliAvailable: isClaudeCliAvailable(),
       publicUrl: settings.publicUrl,
       updateChannel: settings.updateChannel,
       dockerAutoUpdate: settings.dockerAutoUpdate,

package/server/routes.test.ts

@@ -106,6 +106,8 @@ vi.mock("./settings-manager.js", () => ({
     dashboardModel: "claude-haiku-4-5",
     dashboardRunHour: 3,
     dashboardMaxSessionsPerRun: 30,
+    magicUiEnabled: false,
+    magicUiModel: "claude-haiku-4-5",
     publicUrl: "",
     updateChannel: "stable",
     dockerAutoUpdate: false,
@@ -1154,6 +1156,8 @@ describe("GET /api/sessions/:id/archive-info", () => {
       dashboardModel: "claude-haiku-4-5",
       dashboardRunHour: 3,
       dashboardMaxSessionsPerRun: 30,
+      magicUiEnabled: false,
+      magicUiModel: "claude-haiku-4-5",
       publicUrl: "",
       updateChannel: "stable",
       dockerAutoUpdate: false,
@@ -1533,6 +1537,8 @@ describe("GET /api/settings", () => {
       dashboardModel: "claude-haiku-4-5",
       dashboardRunHour: 3,
       dashboardMaxSessionsPerRun: 30,
+      magicUiEnabled: false,
+      magicUiModel: "claude-haiku-4-5",
       publicUrl: "",
       updateChannel: "stable",
       dockerAutoUpdate: false,
@@ -1570,6 +1576,9 @@ describe("GET /api/settings", () => {
       dashboardModel: "claude-haiku-4-5",
       dashboardRunHour: 3,
       dashboardMaxSessionsPerRun: 30,
+      magicUiEnabled: false,
+      magicUiModel: "claude-haiku-4-5",
+      claudeCliAvailable: false,
       publicUrl: "",
       updateChannel: "stable",
       dockerAutoUpdate: false,
@@ -1607,6 +1616,8 @@ describe("GET /api/settings", () => {
       dashboardModel: "claude-haiku-4-5",
       dashboardRunHour: 3,
       dashboardMaxSessionsPerRun: 30,
+      magicUiEnabled: false,
+      magicUiModel: "claude-haiku-4-5",
       publicUrl: "",
       updateChannel: "stable",
       dockerAutoUpdate: false,
@@ -1644,6 +1655,9 @@ describe("GET /api/settings", () => {
       dashboardModel: "claude-haiku-4-5",
       dashboardRunHour: 3,
       dashboardMaxSessionsPerRun: 30,
+      magicUiEnabled: false,
+      magicUiModel: "claude-haiku-4-5",
+      claudeCliAvailable: false,
       publicUrl: "",
       updateChannel: "stable",
       dockerAutoUpdate: false,
@@ -1682,6 +1696,8 @@ describe("GET /api/settings", () => {
       dashboardModel: "claude-haiku-4-5",
       dashboardRunHour: 3,
       dashboardMaxSessionsPerRun: 30,
+      magicUiEnabled: false,
+      magicUiModel: "claude-haiku-4-5",
       publicUrl: "https://example.com",
       updateChannel: "stable",
       dockerAutoUpdate: false,
@@ -1728,6 +1744,8 @@ describe("PUT /api/settings", () => {
       dashboardModel: "claude-haiku-4-5",
       dashboardRunHour: 3,
       dashboardMaxSessionsPerRun: 30,
+      magicUiEnabled: false,
+      magicUiModel: "claude-haiku-4-5",
       publicUrl: "",
       updateChannel: "stable",
       dockerAutoUpdate: false,
@@ -1787,6 +1805,9 @@ describe("PUT /api/settings", () => {
       dashboardModel: "claude-haiku-4-5",
       dashboardRunHour: 3,
       dashboardMaxSessionsPerRun: 30,
+      magicUiEnabled: false,
+      magicUiModel: "claude-haiku-4-5",
+      claudeCliAvailable: false,
       publicUrl: "",
       updateChannel: "stable",
       dockerAutoUpdate: false,
@@ -1824,6 +1845,8 @@ describe("PUT /api/settings", () => {
       dashboardModel: "claude-haiku-4-5",
       dashboardRunHour: 3,
       dashboardMaxSessionsPerRun: 30,
+      magicUiEnabled: false,
+      magicUiModel: "claude-haiku-4-5",
       publicUrl: "",
       updateChannel: "stable",
       dockerAutoUpdate: false,
@@ -1878,6 +1901,8 @@ describe("PUT /api/settings", () => {
       dashboardModel: "claude-haiku-4-5",
       dashboardRunHour: 3,
       dashboardMaxSessionsPerRun: 30,
+      magicUiEnabled: false,
+      magicUiModel: "claude-haiku-4-5",
       publicUrl: "",
       updateChannel: "stable",
       dockerAutoUpdate: false,
@@ -2032,6 +2057,8 @@ describe("PUT /api/settings", () => {
       dashboardModel: "claude-haiku-4-5",
       dashboardRunHour: 3,
       dashboardMaxSessionsPerRun: 30,
+      magicUiEnabled: false,
+      magicUiModel: "claude-haiku-4-5",
       publicUrl: "https://my-server.com",
       updateChannel: "stable",
       dockerAutoUpdate: false,
@@ -2292,6 +2319,8 @@ describe("GET /api/linear/issues", () => {
       dashboardModel: "claude-haiku-4-5",
       dashboardRunHour: 3,
       dashboardMaxSessionsPerRun: 30,
+      magicUiEnabled: false,
+      magicUiModel: "claude-haiku-4-5",
       publicUrl: "",
       updateChannel: "stable",
       dockerAutoUpdate: false,
@@ -2336,6 +2365,8 @@ describe("GET /api/linear/issues", () => {
       dashboardModel: "claude-haiku-4-5",
       dashboardRunHour: 3,
       dashboardMaxSessionsPerRun: 30,
+      magicUiEnabled: false,
+      magicUiModel: "claude-haiku-4-5",
       publicUrl: "",
       updateChannel: "stable",
       dockerAutoUpdate: false,
@@ -2433,6 +2464,8 @@ describe("GET /api/linear/issues", () => {
       dashboardModel: "claude-haiku-4-5",
       dashboardRunHour: 3,
       dashboardMaxSessionsPerRun: 30,
+      magicUiEnabled: false,
+      magicUiModel: "claude-haiku-4-5",
       publicUrl: "",
       updateChannel: "stable",
       dockerAutoUpdate: false,
@@ -2537,6 +2570,8 @@ describe("GET /api/linear/issues", () => {
       dashboardModel: "claude-haiku-4-5",
       dashboardRunHour: 3,
       dashboardMaxSessionsPerRun: 30,
+      magicUiEnabled: false,
+      magicUiModel: "claude-haiku-4-5",
       publicUrl: "",
       updateChannel: "stable",
       dockerAutoUpdate: false,
@@ -2606,6 +2641,8 @@ describe("GET /api/linear/connection", () => {
       dashboardModel: "claude-haiku-4-5",
       dashboardRunHour: 3,
       dashboardMaxSessionsPerRun: 30,
+      magicUiEnabled: false,
+      magicUiModel: "claude-haiku-4-5",
       publicUrl: "",
       updateChannel: "stable",
       dockerAutoUpdate: false,
@@ -2650,6 +2687,8 @@ describe("GET /api/linear/connection", () => {
       dashboardModel: "claude-haiku-4-5",
       dashboardRunHour: 3,
       dashboardMaxSessionsPerRun: 30,
+      magicUiEnabled: false,
+      magicUiModel: "claude-haiku-4-5",
       publicUrl: "",
       updateChannel: "stable",
       dockerAutoUpdate: false,
@@ -2716,6 +2755,8 @@ describe("POST /api/linear/issues/:id/transition", () => {
       dashboardModel: "claude-haiku-4-5",
       dashboardRunHour: 3,
       dashboardMaxSessionsPerRun: 30,
+      magicUiEnabled: false,
+      magicUiModel: "claude-haiku-4-5",
       publicUrl: "",
       updateChannel: "stable",
       dockerAutoUpdate: false,
@@ -2764,6 +2805,8 @@ describe("POST /api/linear/issues/:id/transition", () => {
       dashboardModel: "claude-haiku-4-5",
       dashboardRunHour: 3,
       dashboardMaxSessionsPerRun: 30,
+      magicUiEnabled: false,
+      magicUiModel: "claude-haiku-4-5",
       publicUrl: "",
       updateChannel: "stable",
       dockerAutoUpdate: false,
@@ -2811,6 +2854,8 @@ describe("POST /api/linear/issues/:id/transition", () => {
       dashboardModel: "claude-haiku-4-5",
       dashboardRunHour: 3,
       dashboardMaxSessionsPerRun: 30,
+      magicUiEnabled: false,
+      magicUiModel: "claude-haiku-4-5",
       publicUrl: "",
       updateChannel: "stable",
       dockerAutoUpdate: false,
@@ -2860,6 +2905,8 @@ describe("POST /api/linear/issues/:id/transition", () => {
       dashboardModel: "claude-haiku-4-5",
       dashboardRunHour: 3,
       dashboardMaxSessionsPerRun: 30,
+      magicUiEnabled: false,
+      magicUiModel: "claude-haiku-4-5",
       publicUrl: "",
       updateChannel: "stable",
       dockerAutoUpdate: false,
@@ -2943,6 +2990,8 @@ describe("POST /api/linear/issues/:id/transition", () => {
       dashboardModel: "claude-haiku-4-5",
       dashboardRunHour: 3,
       dashboardMaxSessionsPerRun: 30,
+      magicUiEnabled: false,
+      magicUiModel: "claude-haiku-4-5",
       publicUrl: "",
       updateChannel: "stable",
       dockerAutoUpdate: false,
@@ -3005,6 +3054,8 @@ describe("GET /api/linear/projects", () => {
       dashboardModel: "claude-haiku-4-5",
       dashboardRunHour: 3,
       dashboardMaxSessionsPerRun: 30,
+      magicUiEnabled: false,
+      magicUiModel: "claude-haiku-4-5",
       publicUrl: "",
       updateChannel: "stable",
       dockerAutoUpdate: false,
@@ -3049,6 +3100,8 @@ describe("GET /api/linear/projects", () => {
       dashboardModel: "claude-haiku-4-5",
       dashboardRunHour: 3,
       dashboardMaxSessionsPerRun: 30,
+      magicUiEnabled: false,
+      magicUiModel: "claude-haiku-4-5",
       publicUrl: "",
       updateChannel: "stable",
       dockerAutoUpdate: false,
@@ -3123,6 +3176,8 @@ describe("GET /api/linear/project-issues", () => {
       dashboardModel: "claude-haiku-4-5",
       dashboardRunHour: 3,
       dashboardMaxSessionsPerRun: 30,
+      magicUiEnabled: false,
+      magicUiModel: "claude-haiku-4-5",
       publicUrl: "",
       updateChannel: "stable",
       dockerAutoUpdate: false,
@@ -3167,6 +3222,8 @@ describe("GET /api/linear/project-issues", () => {
       dashboardModel: "claude-haiku-4-5",
       dashboardRunHour: 3,
       dashboardMaxSessionsPerRun: 30,
+      magicUiEnabled: false,
+      magicUiModel: "claude-haiku-4-5",
       publicUrl: "",
       updateChannel: "stable",
       dockerAutoUpdate: false,
@@ -3256,6 +3313,8 @@ describe("GET /api/linear/project-issues", () => {
       dashboardModel: "claude-haiku-4-5",
       dashboardRunHour: 3,
       dashboardMaxSessionsPerRun: 30,
+      magicUiEnabled: false,
+      magicUiModel: "claude-haiku-4-5",
       publicUrl: "",
       updateChannel: "stable",
       dockerAutoUpdate: false,

package/server/session-types.ts

@@ -400,6 +400,8 @@ export type BrowserOutgoingMessage =
   | { type: "mcp_reconnect"; serverName: string; client_msg_id?: string }
   | { type: "mcp_set_servers"; servers: Record<string, McpServerConfig>; client_msg_id?: string }
   | { type: "set_ai_validation"; aiValidationEnabled?: boolean | null; aiValidationAutoApprove?: boolean | null; aiValidationAutoDeny?: boolean | null; client_msg_id?: string }
+  | { type: "set_magic_ui"; magicUiActive?: boolean | null; client_msg_id?: string }
+  | { type: "magic_ui_sync"; client_msg_id?: string }
   | { type: "end_session"; reason?: string; client_msg_id?: string }
   | { type: "stop_task"; task_id: string; client_msg_id?: string }
   | { type: "update_environment_variables"; variables: Record<string, string>; client_msg_id?: string };
@@ -442,7 +444,12 @@ export type BrowserIncomingMessageBase =
   | { type: "session_phase"; phase: SessionPhase; previousPhase: SessionPhase }
   | { type: "prompt_suggestion"; suggestions: string[] }
   | { type: "streamlined_text"; text: string }
-  | { type: "streamlined_tool_use_summary"; tool_summary: string };
+  | { type: "streamlined_tool_use_summary"; tool_summary: string }
+  // MagicUI: the server always sends the full canonical dashboard state
+  // (small by construction — capped slots/logs). The iframe runtime diffs
+  // against its DOM via per-slot updatedAt, so no client-side reducer and no
+  // version-gap protocol is needed; late joiners are trivially correct.
+  | { type: "magic_ui_state"; state: import("./magic-ui-types.js").MagicUiDashboardState };
 
 export type BrowserIncomingMessage = BrowserIncomingMessageBase & { seq?: number };
 
@@ -508,6 +515,13 @@ export interface SessionState {
   aiValidationAutoApprove?: boolean | null;
   /** Per-session auto-deny override. null/undefined = use global default */
   aiValidationAutoDeny?: boolean | null;
+  /**
+   * Per-session MagicUI opt-in. null/undefined = use the global
+   * magicUiEnabled default. When effective-true (and the Claude CLI is
+   * available), browsers render the MagicUI dashboard view and the server
+   * runs a Haiku watcher for this session.
+   */
+  magicUiActive?: boolean | null;
   /** If this session is linked to a Linear agent session */
   linearSessionId?: string;
 }

package/server/settings-manager.test.ts

@@ -49,6 +49,8 @@ describe("settings-manager", () => {
       dashboardModel: "claude-haiku-4-5",
       dashboardRunHour: 3,
       dashboardMaxSessionsPerRun: 30,
+      magicUiEnabled: false,
+      magicUiModel: "claude-haiku-4-5",
       publicUrl: "",
       updateChannel: "stable",
       dockerAutoUpdate: false,
@@ -117,6 +119,8 @@ describe("settings-manager", () => {
       dashboardModel: "claude-haiku-4-5",
       dashboardRunHour: 3,
       dashboardMaxSessionsPerRun: 30,
+      magicUiEnabled: false,
+      magicUiModel: "claude-haiku-4-5",
       publicUrl: "",
       updateChannel: "stable",
       dockerAutoUpdate: false,
@@ -211,6 +215,8 @@ describe("settings-manager", () => {
       dashboardModel: "claude-haiku-4-5",
       dashboardRunHour: 3,
       dashboardMaxSessionsPerRun: 30,
+      magicUiEnabled: false,
+      magicUiModel: "claude-haiku-4-5",
       publicUrl: "",
       updateChannel: "stable",
       dockerAutoUpdate: false,

package/server/settings-manager.ts

@@ -20,6 +20,12 @@ export const DASHBOARD_MODEL_OPTIONS = [
   "claude-sonnet-5",
 ] as const;
 export const DEFAULT_DASHBOARD_RUN_HOUR = 3;
+
+/**
+ * The MagicUI watcher streams many small turns per session, so it defaults to
+ * the cheapest capable model. Shares the dashboard model option list.
+ */
+export const DEFAULT_MAGIC_UI_MODEL = DEFAULT_DASHBOARD_MODEL;
 export const DEFAULT_DASHBOARD_MAX_SESSIONS_PER_RUN = 30;
 
 export type UpdateChannel = "stable" | "prerelease";
@@ -83,6 +89,14 @@ export interface CompanionSettings {
   dashboardRunHour: number;
   /** Cost safety valve: max sessions summarized per run. */
   dashboardMaxSessionsPerRun: number;
+  /**
+   * Makes the MagicUI session view available to users (default off). Users
+   * still opt in per session; see SessionState.magicUiActive. Requires the
+   * Claude CLI login — the watcher runs on the subscription, never an API key.
+   */
+  magicUiEnabled: boolean;
+  /** Model used by the MagicUI watcher. Cheap-by-default (Haiku). */
+  magicUiModel: string;
   publicUrl: string;
   updateChannel: UpdateChannel;
   dockerAutoUpdate: boolean;
@@ -176,6 +190,8 @@ let settings: CompanionSettings = {
   dashboardModel: DEFAULT_DASHBOARD_MODEL,
   dashboardRunHour: DEFAULT_DASHBOARD_RUN_HOUR,
   dashboardMaxSessionsPerRun: DEFAULT_DASHBOARD_MAX_SESSIONS_PER_RUN,
+  magicUiEnabled: false,
+  magicUiModel: DEFAULT_MAGIC_UI_MODEL,
   publicUrl: "",
   updateChannel: "stable",
   dockerAutoUpdate: false,
@@ -231,6 +247,11 @@ function normalize(raw: Partial<CompanionSettings> | null | undefined): Companio
         && raw.dashboardMaxSessionsPerRun >= 1 && raw.dashboardMaxSessionsPerRun <= 200
         ? raw.dashboardMaxSessionsPerRun
         : DEFAULT_DASHBOARD_MAX_SESSIONS_PER_RUN,
+    magicUiEnabled: typeof raw?.magicUiEnabled === "boolean" ? raw.magicUiEnabled : false,
+    magicUiModel:
+      typeof raw?.magicUiModel === "string" && raw.magicUiModel.trim()
+        ? raw.magicUiModel.trim()
+        : DEFAULT_MAGIC_UI_MODEL,
     publicUrl: typeof raw?.publicUrl === "string" ? raw.publicUrl.trim().replace(/\/+$/, "") : "",
     updateChannel: raw?.updateChannel === "prerelease" ? "prerelease" : "stable",
     dockerAutoUpdate: typeof raw?.dockerAutoUpdate === "boolean" ? raw.dockerAutoUpdate : false,
@@ -272,7 +293,7 @@ export function getSettings(): CompanionSettings {
 }
 
 export function updateSettings(
-  patch: Partial<Pick<CompanionSettings, "anthropicApiKey" | "anthropicModel" | "claudeCodeOAuthToken" | "openaiApiKey" | "onboardingCompleted" | "linearApiKey" | "linearAutoTransition" | "linearAutoTransitionStateId" | "linearAutoTransitionStateName" | "linearArchiveTransition" | "linearArchiveTransitionStateId" | "linearArchiveTransitionStateName" | "linearOAuthClientId" | "linearOAuthClientSecret" | "linearOAuthWebhookSecret" | "linearOAuthAccessToken" | "linearOAuthRefreshToken" | "aiValidationEnabled" | "aiValidationAutoApprove" | "aiValidationAutoDeny" | "dashboardEnabled" | "dashboardModel" | "dashboardRunHour" | "dashboardMaxSessionsPerRun" | "publicUrl" | "updateChannel" | "dockerAutoUpdate" | "proactiveKeepaliveEnabled" | "keepaliveDetachedSessions" | "wedgeKillEnabled" | "silenceProbeEnabled" | "claudeTransport" | "cliBridgeMode" | "claudeBridgeMode" | "claudeBridgeIngressUrl" | "claudeCompatBannerDismissedVersion">>,
+  patch: Partial<Pick<CompanionSettings, "anthropicApiKey" | "anthropicModel" | "claudeCodeOAuthToken" | "openaiApiKey" | "onboardingCompleted" | "linearApiKey" | "linearAutoTransition" | "linearAutoTransitionStateId" | "linearAutoTransitionStateName" | "linearArchiveTransition" | "linearArchiveTransitionStateId" | "linearArchiveTransitionStateName" | "linearOAuthClientId" | "linearOAuthClientSecret" | "linearOAuthWebhookSecret" | "linearOAuthAccessToken" | "linearOAuthRefreshToken" | "aiValidationEnabled" | "aiValidationAutoApprove" | "aiValidationAutoDeny" | "dashboardEnabled" | "dashboardModel" | "dashboardRunHour" | "dashboardMaxSessionsPerRun" | "magicUiEnabled" | "magicUiModel" | "publicUrl" | "updateChannel" | "dockerAutoUpdate" | "proactiveKeepaliveEnabled" | "keepaliveDetachedSessions" | "wedgeKillEnabled" | "silenceProbeEnabled" | "claudeTransport" | "cliBridgeMode" | "claudeBridgeMode" | "claudeBridgeIngressUrl" | "claudeCompatBannerDismissedVersion">>,
 ): CompanionSettings {
   ensureLoaded();
   settings = normalize({
@@ -300,6 +321,8 @@ export function updateSettings(
     dashboardModel: patch.dashboardModel ?? settings.dashboardModel,
     dashboardRunHour: patch.dashboardRunHour ?? settings.dashboardRunHour,
     dashboardMaxSessionsPerRun: patch.dashboardMaxSessionsPerRun ?? settings.dashboardMaxSessionsPerRun,
+    magicUiEnabled: patch.magicUiEnabled ?? settings.magicUiEnabled,
+    magicUiModel: patch.magicUiModel ?? settings.magicUiModel,
     publicUrl: patch.publicUrl ?? settings.publicUrl,
     updateChannel: patch.updateChannel ?? settings.updateChannel,
     dockerAutoUpdate: patch.dockerAutoUpdate ?? settings.dockerAutoUpdate,

package/server/ws-bridge-browser-ingest.ts

@@ -66,6 +66,7 @@ export const IDEMPOTENT_BROWSER_MESSAGE_TYPES: ReadonlySet<string> = new Set([
   "mcp_reconnect",
   "mcp_set_servers",
   "set_ai_validation",
+  "set_magic_ui",
 ]);
 
 /**

package/server/ws-bridge-codex.test.ts

@@ -136,6 +136,8 @@ describe("attachCodexAdapterHandlers", () => {
       dashboardModel: "claude-haiku-4-5",
       dashboardRunHour: 3,
       dashboardMaxSessionsPerRun: 30,
+      magicUiEnabled: false,
+      magicUiModel: "claude-haiku-4-5",
       publicUrl: "",
       updateChannel: "stable",
       dockerAutoUpdate: false,
@@ -1130,6 +1132,8 @@ describe("attachCodexAdapterHandlers", () => {
         dashboardModel: "claude-haiku-4-5",
         dashboardRunHour: 3,
         dashboardMaxSessionsPerRun: 30,
+        magicUiEnabled: false,
+        magicUiModel: "claude-haiku-4-5",
         publicUrl: "",
         updateChannel: "stable",
         dockerAutoUpdate: false,
@@ -1314,6 +1318,8 @@ describe("attachCodexAdapterHandlers", () => {
         dashboardModel: "claude-haiku-4-5",
         dashboardRunHour: 3,
         dashboardMaxSessionsPerRun: 30,
+        magicUiEnabled: false,
+        magicUiModel: "claude-haiku-4-5",
         publicUrl: "",
         updateChannel: "stable",
         dockerAutoUpdate: false,
@@ -1368,6 +1374,8 @@ describe("attachCodexAdapterHandlers", () => {
         dashboardModel: "claude-haiku-4-5",
         dashboardRunHour: 3,
         dashboardMaxSessionsPerRun: 30,
+        magicUiEnabled: false,
+        magicUiModel: "claude-haiku-4-5",
         publicUrl: "",
         updateChannel: "stable",
         dockerAutoUpdate: false,
@@ -1487,6 +1495,8 @@ describe("attachCodexAdapterHandlers", () => {
         dashboardModel: "claude-haiku-4-5",
         dashboardRunHour: 3,
         dashboardMaxSessionsPerRun: 30,
+        magicUiEnabled: false,
+        magicUiModel: "claude-haiku-4-5",
         publicUrl: "",
         updateChannel: "stable",
         dockerAutoUpdate: false,
@@ -1625,6 +1635,8 @@ describe("attachCodexAdapterHandlers", () => {
         dashboardModel: "claude-haiku-4-5",
         dashboardRunHour: 3,
         dashboardMaxSessionsPerRun: 30,
+        magicUiEnabled: false,
+        magicUiModel: "claude-haiku-4-5",
         publicUrl: "",
         updateChannel: "stable",
         dockerAutoUpdate: false,

package/server/ws-bridge-controls.ts

@@ -1,5 +1,14 @@
 import type { Session } from "./ws-bridge-types.js";
 
+export function handleSetMagicUi(
+  session: Session,
+  msg: { magicUiActive?: boolean | null },
+): void {
+  if (msg.magicUiActive !== undefined) {
+    session.state.magicUiActive = msg.magicUiActive;
+  }
+}
+
 export function handleSetAiValidation(
   session: Session,
   msg: {