npm - @nextclaw/companion - Versions diffs - 0.1.1-beta.0 - Mend

@nextclaw/companion 0.1.1-beta.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (31) hide show

package/CHANGELOG.md +7 -0
package/LICENSE +21 -0
package/dist/src/companion-session-view.service.test.js +27 -0
package/dist/src/launcher/index.js +22 -0
package/dist/src/main.js +22 -0
package/dist/src/preload/index.js +13 -0
package/dist/src/services/companion-application.service.js +68 -0
package/dist/src/services/companion-runtime-client.service.js +88 -0
package/dist/src/services/companion-session-view.service.js +52 -0
package/dist/src/services/companion-tray.service.js +41 -0
package/dist/src/services/companion-window.service.js +106 -0
package/dist/src/stores/companion-runtime-state.store.js +21 -0
package/dist/src/stores/companion-window-position.store.js +30 -0
package/dist/src/types/companion.types.js +2 -0
package/dist/src/utils/companion-renderer-html.utils.js +194 -0
package/package.json +31 -0
package/scripts/smoke.mjs +20 -0
package/src/companion-session-view.service.test.ts +37 -0
package/src/launcher/index.ts +24 -0
package/src/main.ts +23 -0
package/src/preload/index.ts +13 -0
package/src/services/companion-application.service.ts +76 -0
package/src/services/companion-runtime-client.service.ts +118 -0
package/src/services/companion-session-view.service.ts +63 -0
package/src/services/companion-tray.service.ts +44 -0
package/src/services/companion-window.service.ts +115 -0
package/src/stores/companion-runtime-state.store.ts +23 -0
package/src/stores/companion-window-position.store.ts +31 -0
package/src/types/companion.types.ts +37 -0
package/src/utils/companion-renderer-html.utils.ts +192 -0
package/tsconfig.json +13 -0

package/dist/src/utils/companion-renderer-html.utils.js ADDED Viewed

@@ -0,0 +1,194 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.renderCompanionHtml = renderCompanionHtml;
+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>`;
+function renderCompanionHtml() {
+    return COMPANION_HTML;
+}

package/package.json ADDED Viewed

@@ -0,0 +1,31 @@
+{
+  "name": "@nextclaw/companion",
+  "version": "0.1.1-beta.0",
+  "private": false,
+  "description": "Standalone Electron companion shell for active NextClaw agents.",
+  "author": "NextClaw Team",
+  "homepage": "https://github.com/Peiiii/nextclaw",
+  "main": "dist/src/main.js",
+  "bin": {
+    "nextclaw-companion": "dist/src/launcher/index.js"
+  },
+  "license": "MIT",
+  "dependencies": {
+    "electron": "^32.2.1",
+    "@nextclaw/client-sdk": "0.1.1-beta.0"
+  },
+  "devDependencies": {
+    "@types/node": "^20.17.6",
+    "typescript": "^5.6.3",
+    "vitest": "^4.1.2"
+  },
+  "scripts": {
+    "dev": "pnpm build:main && node dist/src/launcher/index.js",
+    "build": "pnpm build:main",
+    "build:main": "node -e \"require('node:fs').rmSync('dist',{recursive:true,force:true})\" && tsc -p tsconfig.json --outDir dist --noEmit false",
+    "lint": "eslint \"src/**/*.ts\"",
+    "tsc": "tsc -p tsconfig.json --noEmit",
+    "test": "vitest run src/companion-session-view.service.test.ts",
+    "smoke": "pnpm build:main && node scripts/smoke.mjs"
+  }
+}

package/scripts/smoke.mjs ADDED Viewed

@@ -0,0 +1,20 @@
+import { existsSync } from "node:fs";
+import { resolve } from "node:path";
+const requiredFiles = [
+  resolve("dist/src/main.js"),
+  resolve("dist/src/launcher/index.js"),
+  resolve("dist/src/preload/index.js")
+];
+const missingFiles = requiredFiles.filter((filePath) => !existsSync(filePath));
+if (missingFiles.length > 0) {
+  console.error("Missing companion build artifacts:");
+  for (const filePath of missingFiles) {
+    console.error(`- ${filePath}`);
+  }
+  process.exit(1);
+}
+console.log("Companion smoke passed.");

package/src/companion-session-view.service.test.ts ADDED Viewed

@@ -0,0 +1,37 @@
+import { describe, expect, it } from "vitest";
+import { CompanionSessionViewService } from "./services/companion-session-view.service.js";
+describe("CompanionSessionViewService", () => {
+  it("prefers the most recently updated running session", () => {
+    const service = new 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" }
+      ]
+    });
+    expect(view.sessionId).toBe("newer");
+    expect(view.title).toBe("Writer");
+  });
+  it("falls back to an idle shell view when no running session exists", () => {
+    const service = new CompanionSessionViewService(
+      "http://127.0.0.1:55667",
+      () => "http://127.0.0.1:55667/api/agents/default/avatar"
+    );
+    const view = service.selectView({
+      agents: [],
+      sessions: []
+    });
+    expect(view.state).toBe("idle");
+    expect(view.subtitle).toBe("No active agent");
+  });
+});

package/src/launcher/index.ts ADDED Viewed

@@ -0,0 +1,24 @@
+#!/usr/bin/env node
+import { spawn } from "node:child_process";
+import { createRequire } from "node:module";
+import { resolve } from "node:path";
+const loadModule = createRequire(__filename);
+const electronBinary = loadModule("electron") as string;
+const appRoot = resolve(__dirname, "..", "..", "..");
+const env = { ...process.env };
+delete env.ELECTRON_RUN_AS_NODE;
+const child = spawn(electronBinary, [appRoot, ...process.argv.slice(2)], {
+  stdio: "inherit",
+  env
+});
+child.on("exit", (code, signal) => {
+  if (signal) {
+    process.kill(process.pid, signal);
+    return;
+  }
+  process.exit(code ?? 0);
+});

package/src/main.ts ADDED Viewed

@@ -0,0 +1,23 @@
+import { CompanionApplicationService } from "./services/companion-application.service.js";
+function resolveBaseUrl(argv: string[]): string {
+  const baseUrlFromCli = argv.find((value) => value.startsWith("--base-url="));
+  if (baseUrlFromCli) {
+    return baseUrlFromCli.slice("--base-url=".length);
+  }
+  const baseUrlFlagIndex = argv.findIndex((value) => value === "--base-url");
+  if (baseUrlFlagIndex >= 0 && argv[baseUrlFlagIndex + 1]) {
+    return argv[baseUrlFlagIndex + 1];
+  }
+  return process.env.NEXTCLAW_COMPANION_BASE_URL?.trim() || "http://127.0.0.1:55667";
+}
+async function main(): Promise<void> {
+  const application = new CompanionApplicationService({
+    baseUrl: resolveBaseUrl(process.argv.slice(1)),
+    runtimeStatePath: process.env.NEXTCLAW_COMPANION_RUNTIME_STATE_PATH?.trim() || undefined
+  });
+  await application.run();
+}
+void main();

package/src/preload/index.ts ADDED Viewed

@@ -0,0 +1,13 @@
+import { contextBridge, ipcRenderer } from "electron";
+import type { CompanionAvatarView } from "../types/companion.types.js";
+contextBridge.exposeInMainWorld("nextclawCompanion", {
+  onView: (listener: (view: CompanionAvatarView) => void) => {
+    ipcRenderer.on("companion:view", (_event, view: CompanionAvatarView) => {
+      listener(view);
+    });
+  },
+  open: () => ipcRenderer.invoke("companion:open"),
+  quit: () => ipcRenderer.invoke("companion:quit"),
+  ready: () => ipcRenderer.send("companion:ready")
+});

package/src/services/companion-application.service.ts ADDED Viewed

@@ -0,0 +1,76 @@
+import { app } from "electron";
+import { resolve } from "node:path";
+import type { CompanionAppOptions } from "../types/companion.types.js";
+import { CompanionRuntimeStateStore } from "../stores/companion-runtime-state.store.js";
+import { CompanionWindowPositionStore } from "../stores/companion-window-position.store.js";
+import { CompanionRuntimeClientService } from "./companion-runtime-client.service.js";
+import { CompanionTrayService } from "./companion-tray.service.js";
+import { CompanionWindowService } from "./companion-window.service.js";
+export class CompanionApplicationService {
+  private readonly runtimeClient: CompanionRuntimeClientService;
+  private readonly runtimeStateStore: CompanionRuntimeStateStore | null;
+  private readonly windowService: CompanionWindowService;
+  private readonly trayService: CompanionTrayService;
+  private quitting = false;
+  constructor(private readonly options: CompanionAppOptions) {
+    const preloadPath = resolve(__dirname, "..", "preload", "index.js");
+    this.runtimeClient = new CompanionRuntimeClientService(options.baseUrl);
+    this.runtimeStateStore = options.runtimeStatePath
+      ? new CompanionRuntimeStateStore(options.runtimeStatePath)
+      : null;
+    this.windowService = new CompanionWindowService(
+      preloadPath,
+      CompanionWindowPositionStore.fromUserData(app.getPath("userData"))
+    );
+    this.trayService = new CompanionTrayService(
+      options.baseUrl,
+      () => this.windowService.toggleVisibility(),
+      () => this.quit()
+    );
+  }
+  readonly run = async (): Promise<void> => {
+    if (!app.requestSingleInstanceLock()) {
+      app.quit();
+      return;
+    }
+    app.on("second-instance", () => {
+      this.windowService.show();
+    });
+    app.on("window-all-closed", () => undefined);
+    app.on("before-quit", () => {
+      this.quitting = true;
+      this.runtimeClient.stop();
+      this.trayService.destroy();
+      this.windowService.destroy();
+      this.runtimeStateStore?.clear();
+    });
+    app.on("activate", () => {
+      this.windowService.show();
+    });
+    await app.whenReady();
+    this.runtimeStateStore?.write({
+      pid: process.pid,
+      startedAt: new Date().toISOString(),
+      baseUrl: this.options.baseUrl
+    });
+    await this.windowService.create();
+    this.windowService.show();
+    this.trayService.create();
+    await this.runtimeClient.start((view) => {
+      this.windowService.updateView(view);
+    });
+  };
+  readonly quit = (): void => {
+    if (this.quitting) {
+      return;
+    }
+    this.quitting = true;
+    app.quit();
+  };
+}

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

@@ -0,0 +1,118 @@
+import type {
+  CompanionAgentProfile,
+  CompanionAvatarView,
+  CompanionSessionSummary
+} from "../types/companion.types.js";
+import { CompanionSessionViewService } from "./companion-session-view.service.js";
+type CompanionSdkClient = {
+  agents: {
+    list: () => Promise<CompanionAgentProfile[]>;
+    resolveAvatarUrl: (agentId: string) => string;
+  };
+  sessions: {
+    list: () => Promise<{ sessions: CompanionSessionSummary[] }>;
+    subscribe: (
+      handler: (event: unknown) => void,
+      options: { reconnectDelayMs?: number; onError?: (error: unknown) => void }
+    ) => { close: () => void };
+  };
+};
+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 stop = (): void => {
+    this.subscription?.close();
+    this.subscription = null;
+    if (this.refreshTimer !== null) {
+      clearInterval(this.refreshTimer);
+      this.refreshTimer = null;
+    }
+  };
+  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
+        )
+      );
+    }
+  };
+  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;
+  };
+  private readonly ensureViewService = (client: CompanionSdkClient): CompanionSessionViewService => {
+    if (this.viewService) {
+      return this.viewService;
+    }
+    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);
+  };
+  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/services/companion-session-view.service.ts ADDED Viewed

@@ -0,0 +1,63 @@
+import type {
+  CompanionAgentProfile,
+  CompanionAvatarView,
+  CompanionOfflineReason,
+  CompanionSessionViewInput
+} from "../types/companion.types.js";
+export class CompanionSessionViewService {
+  constructor(
+    private readonly baseUrl: string,
+    private readonly resolveAvatarUrl: (agentId: string) => string
+  ) {}
+  readonly selectView = (input: CompanionSessionViewInput): CompanionAvatarView => {
+    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
+    };
+  };
+  readonly createOfflineView = (reason?: CompanionOfflineReason): CompanionAvatarView => {
+    return {
+      state: "offline",
+      title: "NextClaw",
+      subtitle: reason?.summary?.trim() || "Runtime unavailable",
+      openUrl: this.baseUrl
+    };
+  };
+  private readonly findAgent = (
+    agents: CompanionAgentProfile[],
+    agentId: string | undefined
+  ): CompanionAgentProfile | null => {
+    if (!agentId) {
+      return null;
+    }
+    return agents.find((agent) => agent.id === agentId) ?? null;
+  };
+  private readonly resolveAvatar = (agent: CompanionAgentProfile | null, agentId: string): string => {
+    return agent?.avatarUrl?.trim() || this.resolveAvatarUrl(agentId);
+  };
+}

package/src/services/companion-tray.service.ts ADDED Viewed

@@ -0,0 +1,44 @@
+import { Menu, Tray, nativeImage, shell } from "electron";
+export class CompanionTrayService {
+  private tray: Tray | null = null;
+  constructor(
+    private readonly baseUrl: string,
+    private readonly onToggleWindow: () => void,
+    private readonly onQuit: () => void
+  ) {}
+  readonly create = (): void => {
+    if (this.tray) {
+      return;
+    }
+    this.tray = new Tray(this.createTrayIcon());
+    this.tray.setToolTip("NextClaw Companion");
+    this.tray.on("click", this.onToggleWindow);
+    this.tray.setContextMenu(
+      Menu.buildFromTemplate([
+        { label: "Show Companion", click: this.onToggleWindow },
+        { label: "Open NextClaw", click: () => void shell.openExternal(this.baseUrl) },
+        { type: "separator" },
+        { label: "Quit", click: this.onQuit }
+      ])
+    );
+  };
+  readonly destroy = (): void => {
+    this.tray?.destroy();
+    this.tray = null;
+  };
+  private readonly createTrayIcon = () => {
+    const svg = encodeURIComponent(
+      `<svg xmlns="http://www.w3.org/2000/svg" width="20" height="20" viewBox="0 0 20 20">
+        <rect x="1" y="1" width="18" height="18" rx="6" fill="#16324f"/>
+        <circle cx="10" cy="10" r="4" fill="#f5f8fb"/>
+      </svg>`
+    );
+    return nativeImage.createFromDataURL(`data:image/svg+xml;charset=utf-8,${svg}`);
+  };
+}