@nextclaw/companion 0.1.1-beta.0

package/CHANGELOG.md

@@ -0,0 +1,7 @@
+# @nextclaw/companion
+
+## 0.1.1-beta.0
+
+### Patch Changes
+
+- @nextclaw/client-sdk@0.1.1-beta.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 NextClaw contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

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

@@ -0,0 +1,27 @@
+"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/launcher/index.js

@@ -0,0 +1,22 @@
+#!/usr/bin/env node
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+const node_child_process_1 = require("node:child_process");
+const node_module_1 = require("node:module");
+const node_path_1 = require("node:path");
+const loadModule = (0, node_module_1.createRequire)(__filename);
+const electronBinary = loadModule("electron");
+const appRoot = (0, node_path_1.resolve)(__dirname, "..", "..", "..");
+const env = { ...process.env };
+delete env.ELECTRON_RUN_AS_NODE;
+const child = (0, node_child_process_1.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/dist/src/main.js

@@ -0,0 +1,22 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+const companion_application_service_js_1 = require("./services/companion-application.service.js");
+function resolveBaseUrl(argv) {
+    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() {
+    const application = new companion_application_service_js_1.CompanionApplicationService({
+        baseUrl: resolveBaseUrl(process.argv.slice(1)),
+        runtimeStatePath: process.env.NEXTCLAW_COMPANION_RUNTIME_STATE_PATH?.trim() || undefined
+    });
+    await application.run();
+}
+void main();

package/dist/src/preload/index.js

@@ -0,0 +1,13 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+const electron_1 = require("electron");
+electron_1.contextBridge.exposeInMainWorld("nextclawCompanion", {
+    onView: (listener) => {
+        electron_1.ipcRenderer.on("companion:view", (_event, view) => {
+            listener(view);
+        });
+    },
+    open: () => electron_1.ipcRenderer.invoke("companion:open"),
+    quit: () => electron_1.ipcRenderer.invoke("companion:quit"),
+    ready: () => electron_1.ipcRenderer.send("companion:ready")
+});

package/dist/src/services/companion-application.service.js

@@ -0,0 +1,68 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.CompanionApplicationService = void 0;
+const electron_1 = require("electron");
+const node_path_1 = require("node:path");
+const companion_runtime_state_store_js_1 = require("../stores/companion-runtime-state.store.js");
+const companion_window_position_store_js_1 = require("../stores/companion-window-position.store.js");
+const companion_runtime_client_service_js_1 = require("./companion-runtime-client.service.js");
+const companion_tray_service_js_1 = require("./companion-tray.service.js");
+const companion_window_service_js_1 = require("./companion-window.service.js");
+class CompanionApplicationService {
+    options;
+    runtimeClient;
+    runtimeStateStore;
+    windowService;
+    trayService;
+    quitting = false;
+    constructor(options) {
+        this.options = options;
+        const preloadPath = (0, node_path_1.resolve)(__dirname, "..", "preload", "index.js");
+        this.runtimeClient = new companion_runtime_client_service_js_1.CompanionRuntimeClientService(options.baseUrl);
+        this.runtimeStateStore = options.runtimeStatePath
+            ? new companion_runtime_state_store_js_1.CompanionRuntimeStateStore(options.runtimeStatePath)
+            : null;
+        this.windowService = new companion_window_service_js_1.CompanionWindowService(preloadPath, companion_window_position_store_js_1.CompanionWindowPositionStore.fromUserData(electron_1.app.getPath("userData")));
+        this.trayService = new companion_tray_service_js_1.CompanionTrayService(options.baseUrl, () => this.windowService.toggleVisibility(), () => this.quit());
+    }
+    run = async () => {
+        if (!electron_1.app.requestSingleInstanceLock()) {
+            electron_1.app.quit();
+            return;
+        }
+        electron_1.app.on("second-instance", () => {
+            this.windowService.show();
+        });
+        electron_1.app.on("window-all-closed", () => undefined);
+        electron_1.app.on("before-quit", () => {
+            this.quitting = true;
+            this.runtimeClient.stop();
+            this.trayService.destroy();
+            this.windowService.destroy();
+            this.runtimeStateStore?.clear();
+        });
+        electron_1.app.on("activate", () => {
+            this.windowService.show();
+        });
+        await electron_1.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);
+        });
+    };
+    quit = () => {
+        if (this.quitting) {
+            return;
+        }
+        this.quitting = true;
+        electron_1.app.quit();
+    };
+}
+exports.CompanionApplicationService = CompanionApplicationService;

package/dist/src/services/companion-runtime-client.service.js

@@ -0,0 +1,88 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.CompanionRuntimeClientService = void 0;
+const companion_session_view_service_js_1 = require("./companion-session-view.service.js");
+class CompanionRuntimeClientService {
+    baseUrl;
+    client = null;
+    viewService = null;
+    refreshTimer = null;
+    subscription = null;
+    constructor(baseUrl) {
+        this.baseUrl = baseUrl;
+    }
+    start = async (onView) => {
+        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);
+    };
+    stop = () => {
+        this.subscription?.close();
+        this.subscription = null;
+        if (this.refreshTimer !== null) {
+            clearInterval(this.refreshTimer);
+            this.refreshTimer = null;
+        }
+    };
+    refresh = async (onView) => {
+        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));
+        }
+    };
+    ensureClient = async () => {
+        if (this.client) {
+            return this.client;
+        }
+        const sdkModule = await import("@nextclaw/client-sdk");
+        this.client = sdkModule.createNextClawClient({ baseUrl: this.baseUrl });
+        return this.client;
+    };
+    ensureViewService = (client) => {
+        if (this.viewService) {
+            return this.viewService;
+        }
+        this.viewService = new companion_session_view_service_js_1.CompanionSessionViewService(this.baseUrl, client.agents.resolveAvatarUrl);
+        return this.viewService;
+    };
+    createOfflineView = (reason) => {
+        const viewService = this.viewService ??
+            new companion_session_view_service_js_1.CompanionSessionViewService(this.baseUrl, (agentId) => `${this.baseUrl}/api/agents/${encodeURIComponent(agentId)}/avatar`);
+        return viewService.createOfflineView(reason);
+    };
+    summarizeOfflineError = (message) => {
+        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";
+    };
+}
+exports.CompanionRuntimeClientService = CompanionRuntimeClientService;

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

@@ -0,0 +1,52 @@
+"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;

package/dist/src/services/companion-tray.service.js

@@ -0,0 +1,41 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.CompanionTrayService = void 0;
+const electron_1 = require("electron");
+class CompanionTrayService {
+    baseUrl;
+    onToggleWindow;
+    onQuit;
+    tray = null;
+    constructor(baseUrl, onToggleWindow, onQuit) {
+        this.baseUrl = baseUrl;
+        this.onToggleWindow = onToggleWindow;
+        this.onQuit = onQuit;
+    }
+    create = () => {
+        if (this.tray) {
+            return;
+        }
+        this.tray = new electron_1.Tray(this.createTrayIcon());
+        this.tray.setToolTip("NextClaw Companion");
+        this.tray.on("click", this.onToggleWindow);
+        this.tray.setContextMenu(electron_1.Menu.buildFromTemplate([
+            { label: "Show Companion", click: this.onToggleWindow },
+            { label: "Open NextClaw", click: () => void electron_1.shell.openExternal(this.baseUrl) },
+            { type: "separator" },
+            { label: "Quit", click: this.onQuit }
+        ]));
+    };
+    destroy = () => {
+        this.tray?.destroy();
+        this.tray = null;
+    };
+    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 electron_1.nativeImage.createFromDataURL(`data:image/svg+xml;charset=utf-8,${svg}`);
+    };
+}
+exports.CompanionTrayService = CompanionTrayService;

package/dist/src/services/companion-window.service.js

@@ -0,0 +1,106 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.CompanionWindowService = void 0;
+const electron_1 = require("electron");
+const companion_renderer_html_utils_js_1 = require("../utils/companion-renderer-html.utils.js");
+class CompanionWindowService {
+    preloadPath;
+    positionStore;
+    window = null;
+    currentView = null;
+    constructor(preloadPath, positionStore) {
+        this.preloadPath = preloadPath;
+        this.positionStore = positionStore;
+    }
+    create = async () => {
+        if (this.window) {
+            return;
+        }
+        const bounds = this.positionStore.read();
+        this.window = new electron_1.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;
+        });
+        electron_1.ipcMain.removeHandler("companion:open");
+        electron_1.ipcMain.handle("companion:open", async () => {
+            const openUrl = this.currentView?.openUrl;
+            if (openUrl) {
+                await electron_1.shell.openExternal(openUrl);
+            }
+            return null;
+        });
+        electron_1.ipcMain.removeHandler("companion:quit");
+        electron_1.ipcMain.handle("companion:quit", async () => {
+            electron_1.app.quit();
+            return null;
+        });
+        electron_1.ipcMain.removeAllListeners("companion:ready");
+        electron_1.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((0, companion_renderer_html_utils_js_1.renderCompanionHtml)())}`);
+    };
+    show = () => {
+        this.window?.showInactive();
+    };
+    toggleVisibility = () => {
+        if (!this.window) {
+            return;
+        }
+        if (this.window.isVisible()) {
+            this.window.hide();
+            return;
+        }
+        this.window.showInactive();
+    };
+    updateView = (view) => {
+        this.currentView = view;
+        this.window?.webContents.send("companion:view", view);
+    };
+    destroy = () => {
+        electron_1.ipcMain.removeHandler("companion:open");
+        electron_1.ipcMain.removeHandler("companion:quit");
+        electron_1.ipcMain.removeAllListeners("companion:ready");
+        this.window?.destroy();
+        this.window = null;
+    };
+    persistBounds = () => {
+        const bounds = this.window?.getBounds();
+        if (!bounds) {
+            return;
+        }
+        this.positionStore.write({
+            x: bounds.x,
+            y: bounds.y
+        });
+    };
+}
+exports.CompanionWindowService = CompanionWindowService;

package/dist/src/stores/companion-runtime-state.store.js

@@ -0,0 +1,21 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.CompanionRuntimeStateStore = void 0;
+const node_fs_1 = require("node:fs");
+const node_path_1 = require("node:path");
+class CompanionRuntimeStateStore {
+    filePath;
+    constructor(filePath) {
+        this.filePath = filePath;
+    }
+    write = (state) => {
+        (0, node_fs_1.mkdirSync)((0, node_path_1.dirname)(this.filePath), { recursive: true });
+        (0, node_fs_1.writeFileSync)(this.filePath, JSON.stringify(state, null, 2));
+    };
+    clear = () => {
+        if ((0, node_fs_1.existsSync)(this.filePath)) {
+            (0, node_fs_1.rmSync)(this.filePath, { force: true });
+        }
+    };
+}
+exports.CompanionRuntimeStateStore = CompanionRuntimeStateStore;

package/dist/src/stores/companion-window-position.store.js

@@ -0,0 +1,30 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.CompanionWindowPositionStore = void 0;
+const node_fs_1 = require("node:fs");
+const node_path_1 = require("node:path");
+class CompanionWindowPositionStore {
+    filePath;
+    constructor(filePath) {
+        this.filePath = filePath;
+    }
+    read = () => {
+        if (!(0, node_fs_1.existsSync)(this.filePath)) {
+            return null;
+        }
+        try {
+            return JSON.parse((0, node_fs_1.readFileSync)(this.filePath, "utf-8"));
+        }
+        catch {
+            return null;
+        }
+    };
+    write = (bounds) => {
+        (0, node_fs_1.mkdirSync)((0, node_path_1.dirname)(this.filePath), { recursive: true });
+        (0, node_fs_1.writeFileSync)(this.filePath, JSON.stringify(bounds, null, 2));
+    };
+    static fromUserData = (userDataPath) => {
+        return new CompanionWindowPositionStore((0, node_path_1.resolve)(userDataPath, "companion-window.json"));
+    };
+}
+exports.CompanionWindowPositionStore = CompanionWindowPositionStore;

package/dist/src/types/companion.types.js

@@ -0,0 +1,2 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });