@nextclaw/companion 0.1.1-beta.0

package/src/services/companion-window.service.ts

@@ -0,0 +1,115 @@
+import { app, BrowserWindow, ipcMain, shell } from "electron";
+import type { CompanionAvatarView } from "../types/companion.types.js";
+import type { CompanionWindowPositionStore } from "../stores/companion-window-position.store.js";
+import { renderCompanionHtml } from "../utils/companion-renderer-html.utils.js";
+
+export class CompanionWindowService {
+  private window: BrowserWindow | null = null;
+  private currentView: CompanionAvatarView | null = null;
+
+  constructor(
+    private readonly preloadPath: string,
+    private readonly positionStore: CompanionWindowPositionStore
+  ) {}
+
+  readonly create = async (): Promise<void> => {
+    if (this.window) {
+      return;
+    }
+
+    const bounds = this.positionStore.read();
+    this.window = new BrowserWindow({
+      width: 112,
+      height: 132,
+      x: bounds?.x,
+      y: bounds?.y,
+      frame: false,
+      transparent: true,
+      resizable: false,
+      movable: true,
+      alwaysOnTop: true,
+      skipTaskbar: true,
+      hasShadow: false,
+      webPreferences: {
+        preload: this.preloadPath,
+        contextIsolation: true,
+        nodeIntegration: false
+      }
+    });
+
+    this.window.on("close", () => {
+      this.persistBounds();
+    });
+    this.window.on("move", () => {
+      this.persistBounds();
+    });
+    this.window.on("moved", () => {
+      this.persistBounds();
+    });
+    this.window.on("closed", () => {
+      this.window = null;
+    });
+
+    ipcMain.removeHandler("companion:open");
+    ipcMain.handle("companion:open", async () => {
+      const openUrl = this.currentView?.openUrl;
+      if (openUrl) {
+        await shell.openExternal(openUrl);
+      }
+      return null;
+    });
+    ipcMain.removeHandler("companion:quit");
+    ipcMain.handle("companion:quit", async () => {
+      app.quit();
+      return null;
+    });
+
+    ipcMain.removeAllListeners("companion:ready");
+    ipcMain.on("companion:ready", () => {
+      if (this.currentView) {
+        this.window?.webContents.send("companion:view", this.currentView);
+      }
+    });
+
+    await this.window.loadURL(`data:text/html;charset=utf-8,${encodeURIComponent(renderCompanionHtml())}`);
+  };
+
+  readonly show = (): void => {
+    this.window?.showInactive();
+  };
+
+  readonly toggleVisibility = (): void => {
+    if (!this.window) {
+      return;
+    }
+    if (this.window.isVisible()) {
+      this.window.hide();
+      return;
+    }
+    this.window.showInactive();
+  };
+
+  readonly updateView = (view: CompanionAvatarView): void => {
+    this.currentView = view;
+    this.window?.webContents.send("companion:view", view);
+  };
+
+  readonly destroy = (): void => {
+    ipcMain.removeHandler("companion:open");
+    ipcMain.removeHandler("companion:quit");
+    ipcMain.removeAllListeners("companion:ready");
+    this.window?.destroy();
+    this.window = null;
+  };
+
+  private readonly persistBounds = (): void => {
+    const bounds = this.window?.getBounds();
+    if (!bounds) {
+      return;
+    }
+    this.positionStore.write({
+      x: bounds.x,
+      y: bounds.y
+    });
+  };
+}

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

@@ -0,0 +1,23 @@
+import { existsSync, mkdirSync, rmSync, writeFileSync } from "node:fs";
+import { dirname } from "node:path";
+
+type CompanionRuntimeState = {
+  pid: number;
+  startedAt: string;
+  baseUrl: string;
+};
+
+export class CompanionRuntimeStateStore {
+  constructor(private readonly filePath: string) {}
+
+  readonly write = (state: CompanionRuntimeState): void => {
+    mkdirSync(dirname(this.filePath), { recursive: true });
+    writeFileSync(this.filePath, JSON.stringify(state, null, 2));
+  };
+
+  readonly clear = (): void => {
+    if (existsSync(this.filePath)) {
+      rmSync(this.filePath, { force: true });
+    }
+  };
+}

package/src/stores/companion-window-position.store.ts

@@ -0,0 +1,31 @@
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { dirname, resolve } from "node:path";
+
+type WindowBounds = {
+  x?: number;
+  y?: number;
+};
+
+export class CompanionWindowPositionStore {
+  constructor(private readonly filePath: string) {}
+
+  readonly read = (): WindowBounds | null => {
+    if (!existsSync(this.filePath)) {
+      return null;
+    }
+    try {
+      return JSON.parse(readFileSync(this.filePath, "utf-8")) as WindowBounds;
+    } catch {
+      return null;
+    }
+  };
+
+  readonly write = (bounds: WindowBounds): void => {
+    mkdirSync(dirname(this.filePath), { recursive: true });
+    writeFileSync(this.filePath, JSON.stringify(bounds, null, 2));
+  };
+
+  static readonly fromUserData = (userDataPath: string): CompanionWindowPositionStore => {
+    return new CompanionWindowPositionStore(resolve(userDataPath, "companion-window.json"));
+  };
+}

package/src/types/companion.types.ts

@@ -0,0 +1,37 @@
+export type CompanionAvatarView = {
+  state: "running" | "idle" | "offline";
+  title: string;
+  subtitle: string;
+  avatarUrl?: string;
+  sessionId?: string;
+  agentId?: string;
+  openUrl: string;
+};
+
+export type CompanionOfflineReason = {
+  summary: string;
+};
+
+export type CompanionAgentProfile = {
+  id: string;
+  displayName?: string;
+  avatarUrl?: string;
+};
+
+export type CompanionSessionSummary = {
+  sessionId: string;
+  agentId?: string;
+  updatedAt: string;
+  messageCount: number;
+  status?: "idle" | "running";
+};
+
+export type CompanionSessionViewInput = {
+  agents: CompanionAgentProfile[];
+  sessions: CompanionSessionSummary[];
+};
+
+export type CompanionAppOptions = {
+  baseUrl: string;
+  runtimeStatePath?: string;
+};

package/src/utils/companion-renderer-html.utils.ts

@@ -0,0 +1,192 @@
+const COMPANION_HTML = `<!doctype html>
+<html lang="en">
+  <head>
+    <meta charset="utf-8" />
+    <meta name="viewport" content="width=device-width,initial-scale=1" />
+    <title>NextClaw Companion</title>
+    <style>
+      :root {
+        color-scheme: light;
+        --ring: rgba(12, 84, 190, 0.2);
+        --panel: rgba(255, 255, 255, 0.88);
+        --ink: #16324f;
+        --muted: #5f6c7c;
+        --idle: #d7dce2;
+        --running: #26a269;
+        --offline: #d64545;
+      }
+      * { box-sizing: border-box; }
+      html, body {
+        margin: 0;
+        width: 100%;
+        height: 100%;
+        overflow: hidden;
+        background: transparent;
+        font-family: "SF Pro Display", "Helvetica Neue", sans-serif;
+      }
+      body {
+        display: grid;
+        place-items: center;
+      }
+      button {
+        border: 0;
+        background: none;
+        padding: 0;
+        cursor: pointer;
+      }
+      .shell {
+        width: 112px;
+        height: 132px;
+        display: grid;
+        justify-items: center;
+        gap: 8px;
+      }
+      .avatar {
+        width: 96px;
+        height: 96px;
+        border-radius: 28px;
+        background: linear-gradient(180deg, rgba(255,255,255,0.98), rgba(235,241,247,0.94));
+        box-shadow: 0 14px 36px rgba(13, 30, 51, 0.16), inset 0 0 0 1px rgba(255,255,255,0.82);
+        position: relative;
+        display: grid;
+        place-items: center;
+        overflow: hidden;
+        -webkit-app-region: drag;
+      }
+      .avatar::after {
+        content: "";
+        position: absolute;
+        inset: 4px;
+        border-radius: 24px;
+        box-shadow: inset 0 0 0 1px var(--ring);
+        pointer-events: none;
+      }
+      .avatar img {
+        width: 100%;
+        height: 100%;
+        object-fit: cover;
+      }
+      .initials {
+        width: 100%;
+        height: 100%;
+        display: grid;
+        place-items: center;
+        color: var(--ink);
+        font-size: 28px;
+        font-weight: 700;
+        letter-spacing: 0;
+        background: radial-gradient(circle at top, rgba(255,255,255,0.98), rgba(223,232,242,0.96));
+      }
+      .status {
+        position: absolute;
+        right: 8px;
+        bottom: 8px;
+        width: 14px;
+        height: 14px;
+        border-radius: 999px;
+        border: 2px solid var(--panel);
+        background: var(--idle);
+      }
+      .status[data-state="running"] { background: var(--running); }
+      .status[data-state="offline"] { background: var(--offline); }
+      .meta {
+        width: 100%;
+        padding: 0 4px;
+        text-align: center;
+        -webkit-app-region: no-drag;
+        cursor: pointer;
+      }
+      .title {
+        color: var(--ink);
+        font-size: 12px;
+        font-weight: 700;
+        line-height: 1.25;
+        white-space: nowrap;
+        overflow: hidden;
+        text-overflow: ellipsis;
+      }
+      .subtitle {
+        color: var(--muted);
+        font-size: 11px;
+        line-height: 1.2;
+        margin-top: 2px;
+        white-space: nowrap;
+        overflow: hidden;
+        text-overflow: ellipsis;
+      }
+      .actions {
+        position: absolute;
+        top: 6px;
+        right: 6px;
+        display: flex;
+        gap: 4px;
+        -webkit-app-region: no-drag;
+      }
+      .icon-button {
+        width: 18px;
+        height: 18px;
+        border-radius: 999px;
+        background: rgba(22, 50, 79, 0.12);
+        color: var(--ink);
+        font-size: 11px;
+        font-weight: 700;
+        display: grid;
+        place-items: center;
+      }
+    </style>
+  </head>
+  <body>
+    <div class="shell">
+      <div class="avatar">
+        <div class="actions">
+          <button class="icon-button" id="close-button" type="button" aria-label="Quit Companion">x</button>
+        </div>
+        <div class="initials" id="initials">NC</div>
+        <img id="avatar-image" alt="" hidden />
+        <span class="status" id="status-dot" data-state="idle"></span>
+      </div>
+      <div class="meta" id="open-button" role="button" tabindex="0" aria-label="Open NextClaw">
+        <div class="title" id="title">NextClaw</div>
+        <div class="subtitle" id="subtitle">Waiting</div>
+      </div>
+    </div>
+    <script>
+      const titleNode = document.getElementById("title");
+      const subtitleNode = document.getElementById("subtitle");
+      const initialsNode = document.getElementById("initials");
+      const avatarImageNode = document.getElementById("avatar-image");
+      const statusNode = document.getElementById("status-dot");
+      const openButtonNode = document.getElementById("open-button");
+      const closeButtonNode = document.getElementById("close-button");
+      const applyView = (view) => {
+        titleNode.textContent = view.title;
+        subtitleNode.textContent = view.subtitle;
+        initialsNode.textContent = (view.title || "NC").slice(0, 2).toUpperCase();
+        statusNode.dataset.state = view.state;
+        if (view.avatarUrl) {
+          avatarImageNode.src = view.avatarUrl;
+          avatarImageNode.hidden = false;
+          initialsNode.hidden = true;
+        } else {
+          avatarImageNode.hidden = true;
+          avatarImageNode.removeAttribute("src");
+          initialsNode.hidden = false;
+        }
+      };
+      window.nextclawCompanion.onView(applyView);
+      openButtonNode.addEventListener("click", () => window.nextclawCompanion.open());
+      openButtonNode.addEventListener("keydown", (event) => {
+        if (event.key === "Enter" || event.key === " ") {
+          event.preventDefault();
+          window.nextclawCompanion.open();
+        }
+      });
+      closeButtonNode.addEventListener("click", () => window.nextclawCompanion.quit());
+      window.nextclawCompanion.ready();
+    </script>
+  </body>
+</html>`;
+
+export function renderCompanionHtml(): string {
+  return COMPANION_HTML;
+}

package/tsconfig.json

@@ -0,0 +1,13 @@
+{
+  "extends": "../../tsconfig.base.json",
+  "compilerOptions": {
+    "noEmit": false,
+    "rootDir": ".",
+    "module": "Node16",
+    "moduleResolution": "Node16",
+    "verbatimModuleSyntax": false,
+    "types": ["node", "electron"],
+    "lib": ["DOM", "ES2022"]
+  },
+  "include": ["src/**/*.ts"]
+}