@nextclaw/companion 0.1.1-beta.0 → 0.1.1-beta.2

package/src/managers/companion-runtime.manager.ts

@@ -0,0 +1,191 @@
+import { CompanionRuntimeClientService } from "../services/companion-runtime-client.service.js";
+import {
+  useCompanionRuntimeStore,
+  createInitialCompanionRuntimeSnapshot,
+  type CompanionRuntimeConnectionState,
+  type CompanionRuntimeSnapshot
+} from "../stores/companion-runtime.store.js";
+import type {
+  CompanionAgentProfile,
+  CompanionAvatarView,
+  CompanionOfflineReason,
+  CompanionSessionSummary
+} from "../types/companion.types.js";
+
+export class CompanionRuntimeManager {
+  private clientService: CompanionRuntimeClientService | null = null;
+  private baseUrl: string | null = null;
+  private refreshTimer: ReturnType<typeof setInterval> | null = null;
+  private subscription: { close: () => void } | null = null;
+  private started = false;
+
+  readonly start = async (baseUrl: string): Promise<void> => {
+    if (this.started && this.baseUrl === baseUrl) {
+      return;
+    }
+    this.stop();
+    this.baseUrl = baseUrl;
+    this.clientService = new CompanionRuntimeClientService(baseUrl);
+    await this.clientService.initialize();
+    useCompanionRuntimeStore.getState().setSnapshot(createInitialCompanionRuntimeSnapshot(baseUrl));
+    await this.refresh();
+    this.subscription = this.ensureClientService().subscribeToSessions(
+      async () => {
+        await this.refresh();
+      },
+      {
+        reconnectDelayMs: 1000,
+        onError: async () => {
+          await this.refresh();
+        }
+      }
+    );
+    this.refreshTimer = setInterval(() => {
+      void this.refresh();
+    }, 10000);
+    this.started = true;
+  };
+
+  readonly stop = (): void => {
+    this.subscription?.close();
+    this.subscription = null;
+    if (this.refreshTimer !== null) {
+      clearInterval(this.refreshTimer);
+      this.refreshTimer = null;
+    }
+    this.clientService = null;
+    this.baseUrl = null;
+    this.started = false;
+    useCompanionRuntimeStore.getState().reset();
+  };
+
+  readonly getSnapshot = (): CompanionRuntimeSnapshot => {
+    return useCompanionRuntimeStore.getState().snapshot;
+  };
+
+  readonly syncRuntimeSnapshot = ({
+    agents,
+    sessions
+  }: {
+    agents: CompanionAgentProfile[];
+    sessions: CompanionSessionSummary[];
+  }): CompanionRuntimeSnapshot => {
+    const baseUrl = this.ensureBaseUrl();
+    const currentView = this.resolveCurrentView({
+      baseUrl,
+      agents,
+      sessions
+    });
+    const connectionState: CompanionRuntimeConnectionState = currentView.state === "running" ? "running" : "idle";
+    const snapshot: CompanionRuntimeSnapshot = {
+      baseUrl,
+      agents,
+      sessions,
+      connectionState,
+      offlineReason: null,
+      currentView
+    };
+    useCompanionRuntimeStore.getState().setSnapshot(snapshot);
+    return snapshot;
+  };
+
+  readonly applyOfflineState = (reason?: CompanionOfflineReason): CompanionRuntimeSnapshot => {
+    const baseUrl = this.baseUrl ?? useCompanionRuntimeStore.getState().snapshot.baseUrl ?? "http://127.0.0.1:55667";
+    const snapshot: CompanionRuntimeSnapshot = {
+      baseUrl,
+      agents: [],
+      sessions: [],
+      connectionState: "offline",
+      offlineReason: reason ?? null,
+      currentView: {
+        state: "offline",
+        title: "NextClaw",
+        subtitle: reason?.summary?.trim() || "Runtime unavailable",
+        openUrl: baseUrl
+      }
+    };
+    useCompanionRuntimeStore.getState().setSnapshot(snapshot);
+    return snapshot;
+  };
+
+  private readonly refresh = async (): Promise<void> => {
+    try {
+      const [agents, sessions] = await Promise.all([
+        this.ensureClientService().listAgents(),
+        this.ensureClientService().listSessions()
+      ]);
+      this.syncRuntimeSnapshot({
+        agents,
+        sessions: sessions.sessions
+      });
+    } catch (error) {
+      this.applyOfflineState(
+        error instanceof Error
+          ? { summary: this.summarizeOfflineError(error.message) }
+          : undefined
+      );
+    }
+  };
+
+  private readonly ensureClientService = (): CompanionRuntimeClientService => {
+    if (!this.clientService) {
+      this.clientService = new CompanionRuntimeClientService(this.ensureBaseUrl());
+    }
+    return this.clientService;
+  };
+
+  private readonly ensureBaseUrl = (): string => {
+    if (!this.baseUrl) {
+      throw new Error("CompanionRuntimeManager baseUrl has not been initialized.");
+    }
+    return this.baseUrl;
+  };
+
+  private readonly resolveCurrentView = ({
+    baseUrl,
+    agents,
+    sessions
+  }: {
+    baseUrl: string;
+    agents: CompanionAgentProfile[];
+    sessions: CompanionSessionSummary[];
+  }): CompanionAvatarView => {
+    const runningSession = [...sessions]
+      .filter((session) => session.status === "running")
+      .sort((left, right) => right.updatedAt.localeCompare(left.updatedAt))[0];
+
+    if (!runningSession) {
+      return {
+        state: "idle",
+        title: "NextClaw",
+        subtitle: "No active agent",
+        openUrl: baseUrl
+      };
+    }
+
+    const agent = agents.find((entry) => entry.id === runningSession.agentId) ?? null;
+
+    return {
+      state: "running",
+      title: agent?.displayName?.trim() || runningSession.agentId || "Active Agent",
+      subtitle: runningSession.sessionId,
+      avatarUrl: runningSession.agentId
+        ? agent?.avatarUrl?.trim() || this.ensureClientService().resolveAvatarUrl(runningSession.agentId)
+        : undefined,
+      sessionId: runningSession.sessionId,
+      agentId: runningSession.agentId,
+      openUrl: baseUrl
+    };
+  };
+
+  private readonly summarizeOfflineError = (message: string): string => {
+    if (/fetch failed/i.test(message)) {
+      return "Cannot reach runtime";
+    }
+    if (/timed out/i.test(message)) {
+      return "Runtime timeout";
+    }
+    const trimmed = message.trim();
+    return trimmed.length > 28 ? `${trimmed.slice(0, 25)}...` : trimmed || "Runtime unavailable";
+  };
+}

package/src/managers/companion-shell.manager.ts

@@ -0,0 +1,21 @@
+import { useCompanionShellStore, type CompanionShellSnapshot } from "../stores/companion-shell.store.js";
+
+export class CompanionShellManager {
+  readonly bootstrap = async (): Promise<CompanionShellSnapshot> => {
+    const bootstrap = await window.nextclawCompanion.getBootstrap();
+    const snapshot: CompanionShellSnapshot = {
+      baseUrl: bootstrap.baseUrl,
+      bootstrapped: true
+    };
+    useCompanionShellStore.getState().setSnapshot(snapshot);
+    return snapshot;
+  };
+
+  readonly open = async (): Promise<void> => {
+    await window.nextclawCompanion.open();
+  };
+
+  readonly quit = async (): Promise<void> => {
+    await window.nextclawCompanion.quit();
+  };
+}

package/src/module-structure.config.json

@@ -0,0 +1,22 @@
+{
+  "contractKind": "legacy",
+  "organizationModel": "legacy-apps-companion-renderer-root",
+  "rootPolicy": "contract-only",
+  "enforcement": "error",
+  "allowedRootDirectories": [
+    "app",
+    "managers",
+    "presenters",
+    "services",
+    "stores",
+    "types"
+  ],
+  "requiredRootDirectories": [
+    "presenters",
+    "managers",
+    "stores"
+  ],
+  "allowedRootFiles": [
+    "module-structure.config.json"
+  ]
+}

package/src/presenters/companion.presenter.ts

@@ -0,0 +1,36 @@
+import { CompanionRuntimeManager } from "../managers/companion-runtime.manager.js";
+import { CompanionShellManager } from "../managers/companion-shell.manager.js";
+
+export class CompanionPresenter {
+  readonly companionRuntimeManager = new CompanionRuntimeManager();
+  readonly companionShellManager = new CompanionShellManager();
+  private bootstrapPromise: Promise<void> | null = null;
+  private bootstrapped = false;
+
+  readonly bootstrap = async (): Promise<void> => {
+    if (this.bootstrapped) {
+      return;
+    }
+    if (this.bootstrapPromise) {
+      return await this.bootstrapPromise;
+    }
+    this.bootstrapPromise = (async () => {
+      const shellSnapshot = await this.companionShellManager.bootstrap();
+      await this.companionRuntimeManager.start(shellSnapshot.baseUrl);
+      this.bootstrapped = true;
+    })();
+    try {
+      await this.bootstrapPromise;
+    } finally {
+      this.bootstrapPromise = null;
+    }
+  };
+
+  readonly shutdown = (): void => {
+    this.companionRuntimeManager.stop();
+    this.bootstrapped = false;
+    this.bootstrapPromise = null;
+  };
+}
+
+export const companionPresenter = new CompanionPresenter();

package/src/services/companion-runtime-client.service.ts

@@ -1,9 +1,4 @@
-import type {
-  CompanionAgentProfile,
-  CompanionAvatarView,
-  CompanionSessionSummary
-} from "../types/companion.types.js";
-import { CompanionSessionViewService } from "./companion-session-view.service.js";
+import type { CompanionAgentProfile, CompanionSessionSummary } from "../types/companion.types.js";
 
 type CompanionSdkClient = {
   agents: {
@@ -21,98 +16,40 @@ type CompanionSdkClient = {
 
 export class CompanionRuntimeClientService {
   private client: CompanionSdkClient | null = null;
-  private viewService: CompanionSessionViewService | null = null;
-  private refreshTimer: ReturnType<typeof setInterval> | null = null;
-  private subscription: { close: () => void } | null = null;
 
   constructor(private readonly baseUrl: string) {}
 
-  readonly start = async (onView: (view: CompanionAvatarView) => void): Promise<void> => {
-    await this.ensureClient();
-    await this.refresh(onView);
-    const client = await this.ensureClient();
-    this.subscription = client.sessions.subscribe(
-      async () => {
-        await this.refresh(onView);
-      },
-      {
-        reconnectDelayMs: 1000,
-        onError: async () => {
-          await this.refresh(onView);
-        }
-      }
-    );
-    this.refreshTimer = setInterval(() => {
-      void this.refresh(onView);
-    }, 10000);
+  readonly listAgents = async (): Promise<CompanionAgentProfile[]> => {
+    return await this.ensureClient().agents.list();
   };
 
-  readonly stop = (): void => {
-    this.subscription?.close();
-    this.subscription = null;
-    if (this.refreshTimer !== null) {
-      clearInterval(this.refreshTimer);
-      this.refreshTimer = null;
-    }
+  readonly listSessions = async (): Promise<{ sessions: CompanionSessionSummary[] }> => {
+    return await this.ensureClient().sessions.list();
   };
 
-  private readonly refresh = async (onView: (view: CompanionAvatarView) => void): Promise<void> => {
-    try {
-      const client = await this.ensureClient();
-      const [agents, sessions] = await Promise.all([
-        client.agents.list(),
-        client.sessions.list()
-      ]);
-      onView(
-        this.ensureViewService(client).selectView({
-          agents,
-          sessions: sessions.sessions
-        })
-      );
-    } catch (error) {
-      console.error("[companion] refresh failed", error);
-      onView(
-        this.createOfflineView(
-          error instanceof Error
-            ? { summary: this.summarizeOfflineError(error.message) }
-            : undefined
-        )
-      );
-    }
+  readonly subscribeToSessions = (
+    handler: (event: unknown) => void,
+    options: { reconnectDelayMs?: number; onError?: (error: unknown) => void }
+  ): { close: () => void } => {
+    return this.ensureClient().sessions.subscribe(handler, options);
   };
 
-  private readonly ensureClient = async (): Promise<CompanionSdkClient> => {
-    if (this.client) {
-      return this.client;
-    }
-    const sdkModule = await import("@nextclaw/client-sdk");
-    this.client = sdkModule.createNextClawClient({ baseUrl: this.baseUrl }) as CompanionSdkClient;
-    return this.client;
+  readonly resolveAvatarUrl = (agentId: string): string => {
+    return `${this.baseUrl}/api/agents/${encodeURIComponent(agentId)}/avatar`;
   };
 
-  private readonly ensureViewService = (client: CompanionSdkClient): CompanionSessionViewService => {
-    if (this.viewService) {
-      return this.viewService;
+  private readonly ensureClient = (): CompanionSdkClient => {
+    if (this.client) {
+      return this.client;
     }
-    this.viewService = new CompanionSessionViewService(this.baseUrl, client.agents.resolveAvatarUrl);
-    return this.viewService;
-  };
-
-  private readonly createOfflineView = (reason?: { summary: string }): CompanionAvatarView => {
-    const viewService =
-      this.viewService ??
-      new CompanionSessionViewService(this.baseUrl, (agentId) => `${this.baseUrl}/api/agents/${encodeURIComponent(agentId)}/avatar`);
-    return viewService.createOfflineView(reason);
+    throw new Error("Companion runtime client has not been initialized.");
   };
 
-  private readonly summarizeOfflineError = (message: string): string => {
-    if (/fetch failed/i.test(message)) {
-      return "Cannot reach runtime";
-    }
-    if (/timed out/i.test(message)) {
-      return "Runtime timeout";
+  readonly initialize = async (): Promise<void> => {
+    if (this.client) {
+      return;
     }
-    const trimmed = message.trim();
-    return trimmed.length > 28 ? `${trimmed.slice(0, 25)}...` : trimmed || "Runtime unavailable";
+    const sdkModule = await import("@nextclaw/client-sdk");
+    this.client = sdkModule.createNextClawClient({ baseUrl: this.baseUrl }) as CompanionSdkClient;
   };
 }

package/src/stores/companion-runtime.store.ts

@@ -0,0 +1,51 @@
+import { create } from "zustand";
+
+import type {
+  CompanionAgentProfile,
+  CompanionAvatarView,
+  CompanionOfflineReason,
+  CompanionSessionSummary
+} from "../types/companion.types.js";
+
+export type CompanionRuntimeConnectionState = "loading" | "idle" | "running" | "offline";
+
+export type CompanionRuntimeSnapshot = {
+  baseUrl: string | null;
+  agents: CompanionAgentProfile[];
+  sessions: CompanionSessionSummary[];
+  connectionState: CompanionRuntimeConnectionState;
+  offlineReason: CompanionOfflineReason | null;
+  currentView: CompanionAvatarView;
+};
+
+type CompanionRuntimeStoreState = {
+  snapshot: CompanionRuntimeSnapshot;
+  setSnapshot: (snapshot: CompanionRuntimeSnapshot) => void;
+  reset: () => void;
+};
+
+export const createInitialCompanionRuntimeSnapshot = (
+  baseUrl: string | null = null
+): CompanionRuntimeSnapshot => ({
+  baseUrl,
+  agents: [],
+  sessions: [],
+  connectionState: "loading",
+  offlineReason: null,
+  currentView: {
+    state: "idle",
+    title: "NextClaw",
+    subtitle: "Starting companion",
+    openUrl: baseUrl ?? "http://127.0.0.1:55667"
+  }
+});
+
+export const useCompanionRuntimeStore = create<CompanionRuntimeStoreState>((set) => ({
+  snapshot: createInitialCompanionRuntimeSnapshot(),
+  setSnapshot: (snapshot) => {
+    set({ snapshot });
+  },
+  reset: () => {
+    set({ snapshot: createInitialCompanionRuntimeSnapshot() });
+  }
+}));

package/src/stores/companion-shell.store.ts

@@ -0,0 +1,27 @@
+import { create } from "zustand";
+
+export type CompanionShellSnapshot = {
+  baseUrl: string;
+  bootstrapped: boolean;
+};
+
+type CompanionShellStoreState = {
+  snapshot: CompanionShellSnapshot;
+  setSnapshot: (snapshot: CompanionShellSnapshot) => void;
+  reset: () => void;
+};
+
+export const createInitialCompanionShellSnapshot = (): CompanionShellSnapshot => ({
+  baseUrl: "http://127.0.0.1:55667",
+  bootstrapped: false
+});
+
+export const useCompanionShellStore = create<CompanionShellStoreState>((set) => ({
+  snapshot: createInitialCompanionShellSnapshot(),
+  setSnapshot: (snapshot) => {
+    set({ snapshot });
+  },
+  reset: () => {
+    set({ snapshot: createInitialCompanionShellSnapshot() });
+  }
+}));

package/src/types/companion-bridge.types.d.ts

@@ -0,0 +1,11 @@
+declare global {
+  interface Window {
+    nextclawCompanion: {
+      open: () => Promise<void>;
+      quit: () => Promise<void>;
+      getBootstrap: () => Promise<{ baseUrl: string }>;
+    };
+  }
+}
+
+export {};

package/src/types/companion.types.ts

@@ -25,13 +25,3 @@ export type CompanionSessionSummary = {
   messageCount: number;
   status?: "idle" | "running";
 };
-
-export type CompanionSessionViewInput = {
-  agents: CompanionAgentProfile[];
-  sessions: CompanionSessionSummary[];
-};
-
-export type CompanionAppOptions = {
-  baseUrl: string;
-  runtimeStatePath?: string;
-};

package/tailwind.config.mjs

@@ -0,0 +1,32 @@
+/** @type {import('tailwindcss').Config} */
+export default {
+  darkMode: ["class"],
+  content: [
+    "./index.html",
+    "./src/**/*.{ts,tsx}"
+  ],
+  theme: {
+    extend: {
+      colors: {
+        border: "rgb(203 213 225 / <alpha-value>)",
+        background: "rgb(248 250 252 / <alpha-value>)",
+        foreground: "rgb(15 23 42 / <alpha-value>)",
+        muted: "rgb(241 245 249 / <alpha-value>)",
+        "muted-foreground": "rgb(71 85 105 / <alpha-value>)",
+        accent: "rgb(255 255 255 / <alpha-value>)",
+        primary: "rgb(37 99 235 / <alpha-value>)",
+        success: "rgb(22 163 74 / <alpha-value>)",
+        danger: "rgb(220 38 38 / <alpha-value>)"
+      },
+      borderRadius: {
+        lg: "0.75rem",
+        xl: "1rem",
+        "2xl": "1.5rem"
+      },
+      boxShadow: {
+        companion: "0 18px 44px rgba(15, 23, 42, 0.18)"
+      }
+    }
+  },
+  plugins: []
+};

package/tsconfig.json

@@ -6,8 +6,9 @@
     "module": "Node16",
     "moduleResolution": "Node16",
     "verbatimModuleSyntax": false,
+    "jsx": "react-jsx",
     "types": ["node", "electron"],
     "lib": ["DOM", "ES2022"]
   },
-  "include": ["src/**/*.ts"]
+  "include": ["electron/**/*.ts", "src/**/*.ts", "src/**/*.tsx"]
 }

package/vite.config.mts

@@ -0,0 +1,16 @@
+import path from "node:path";
+import { defineConfig } from "vite";
+import react from "@vitejs/plugin-react";
+
+export default defineConfig({
+  plugins: [react()],
+  resolve: {
+    alias: {
+      "@": path.resolve(__dirname, "./src")
+    }
+  },
+  build: {
+    outDir: "dist/ui",
+    emptyOutDir: false
+  }
+});

package/dist/src/companion-session-view.service.test.js

@@ -1,27 +0,0 @@
-"use strict";
-Object.defineProperty(exports, "__esModule", { value: true });
-const vitest_1 = require("vitest");
-const companion_session_view_service_js_1 = require("./services/companion-session-view.service.js");
-(0, vitest_1.describe)("CompanionSessionViewService", () => {
-    (0, vitest_1.it)("prefers the most recently updated running session", () => {
-        const service = new companion_session_view_service_js_1.CompanionSessionViewService("http://127.0.0.1:55667", (agentId) => `http://127.0.0.1:55667/api/agents/${agentId}/avatar`);
-        const view = service.selectView({
-            agents: [{ id: "writer", displayName: "Writer" }],
-            sessions: [
-                { sessionId: "older", agentId: "writer", messageCount: 1, updatedAt: "2026-05-05T00:00:00.000Z", status: "running" },
-                { sessionId: "newer", agentId: "writer", messageCount: 2, updatedAt: "2026-05-06T00:00:00.000Z", status: "running" }
-            ]
-        });
-        (0, vitest_1.expect)(view.sessionId).toBe("newer");
-        (0, vitest_1.expect)(view.title).toBe("Writer");
-    });
-    (0, vitest_1.it)("falls back to an idle shell view when no running session exists", () => {
-        const service = new companion_session_view_service_js_1.CompanionSessionViewService("http://127.0.0.1:55667", () => "http://127.0.0.1:55667/api/agents/default/avatar");
-        const view = service.selectView({
-            agents: [],
-            sessions: []
-        });
-        (0, vitest_1.expect)(view.state).toBe("idle");
-        (0, vitest_1.expect)(view.subtitle).toBe("No active agent");
-    });
-});

package/dist/src/services/companion-session-view.service.js

@@ -1,52 +0,0 @@
-"use strict";
-Object.defineProperty(exports, "__esModule", { value: true });
-exports.CompanionSessionViewService = void 0;
-class CompanionSessionViewService {
-    baseUrl;
-    resolveAvatarUrl;
-    constructor(baseUrl, resolveAvatarUrl) {
-        this.baseUrl = baseUrl;
-        this.resolveAvatarUrl = resolveAvatarUrl;
-    }
-    selectView = (input) => {
-        const runningSession = [...input.sessions]
-            .filter((session) => session.status === "running")
-            .sort((left, right) => right.updatedAt.localeCompare(left.updatedAt))[0];
-        if (!runningSession) {
-            return {
-                state: "idle",
-                title: "NextClaw",
-                subtitle: "No active agent",
-                openUrl: this.baseUrl
-            };
-        }
-        const agent = this.findAgent(input.agents, runningSession.agentId);
-        return {
-            state: "running",
-            title: agent?.displayName?.trim() || runningSession.agentId || "Active Agent",
-            subtitle: runningSession.sessionId,
-            avatarUrl: runningSession.agentId ? this.resolveAvatar(agent, runningSession.agentId) : undefined,
-            sessionId: runningSession.sessionId,
-            agentId: runningSession.agentId,
-            openUrl: this.baseUrl
-        };
-    };
-    createOfflineView = (reason) => {
-        return {
-            state: "offline",
-            title: "NextClaw",
-            subtitle: reason?.summary?.trim() || "Runtime unavailable",
-            openUrl: this.baseUrl
-        };
-    };
-    findAgent = (agents, agentId) => {
-        if (!agentId) {
-            return null;
-        }
-        return agents.find((agent) => agent.id === agentId) ?? null;
-    };
-    resolveAvatar = (agent, agentId) => {
-        return agent?.avatarUrl?.trim() || this.resolveAvatarUrl(agentId);
-    };
-}
-exports.CompanionSessionViewService = CompanionSessionViewService;