arcane-agents 0.1.0

package/dist/server/server/http/routes/registerApiRoutes.js

@@ -0,0 +1,146 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.registerApiRoutes = registerApiRoutes;
+const voiceLineCatalog_1 = require("../../assets/voiceLineCatalog");
+const appError_1 = require("../appError");
+const errorResponse_1 = require("../errorResponse");
+const requestParsers_1 = require("../requestParsers");
+function registerApiRoutes(app, { orchestrator, hub, statusMonitor }) {
+    app.get("/api/health", (_req, res) => {
+        res.json({
+            ok: true,
+            time: new Date().toISOString()
+        });
+    });
+    app.get("/api/config", (_req, res) => {
+        res.json(orchestrator.getConfig());
+    });
+    app.get("/api/avatars/:avatarType/voice-lines", (req, res) => {
+        const avatarType = req.params.avatarType;
+        const files = (0, voiceLineCatalog_1.listAvatarVoiceLineFiles)(avatarType);
+        res.json({
+            avatarType,
+            files
+        });
+    });
+    app.get("/api/workers", (_req, res) => {
+        res.json({
+            workers: orchestrator.listWorkers()
+        });
+    });
+    app.get("/api/status-debug", (_req, res) => {
+        res.json({
+            workers: statusMonitor.listWorkerStatusDebug(),
+            performance: statusMonitor.getStatusPerformanceDebug()
+        });
+    });
+    app.get("/api/workers/:workerId/status-debug", (req, res) => {
+        const debug = statusMonitor.getWorkerStatusDebug(req.params.workerId);
+        if (!debug) {
+            res.status(404).json({
+                error: `No status debug snapshot found for agent '${req.params.workerId}'.`
+            });
+            return;
+        }
+        res.json({
+            ...debug,
+            transitions: statusMonitor.getWorkerStatusHistory(req.params.workerId)
+        });
+    });
+    app.get("/api/workers/:workerId/status-history", (req, res) => {
+        res.json({
+            workerId: req.params.workerId,
+            transitions: statusMonitor.getWorkerStatusHistory(req.params.workerId)
+        });
+    });
+    app.post("/api/workers/spawn", async (req, res) => {
+        try {
+            const spawnInput = (0, requestParsers_1.parseSpawnInput)(req.body);
+            const worker = await orchestrator.spawn(spawnInput);
+            hub.broadcast({ type: "worker-created", worker });
+            res.status(201).json(worker);
+        }
+        catch (error) {
+            (0, errorResponse_1.handleRequestError)(res, error);
+        }
+    });
+    app.post("/api/workers/:workerId/stop", async (req, res) => {
+        try {
+            const result = await orchestrator.stop(req.params.workerId);
+            if (result.removed) {
+                hub.broadcast({ type: "worker-removed", workerId: result.workerId });
+            }
+            res.json({ ok: true, ...result });
+        }
+        catch (error) {
+            (0, errorResponse_1.handleRequestError)(res, error);
+        }
+    });
+    app.patch("/api/workers/:workerId/position", (req, res) => {
+        try {
+            const x = Number(req.body?.x);
+            const y = Number(req.body?.y);
+            if (!Number.isFinite(x) || !Number.isFinite(y)) {
+                throw (0, appError_1.validationError)("Position requires numeric x and y values.", "position_invalid_payload");
+            }
+            const worker = orchestrator.updatePosition(req.params.workerId, { x, y });
+            hub.broadcast({ type: "worker-updated", worker });
+            res.json(worker);
+        }
+        catch (error) {
+            (0, errorResponse_1.handleRequestError)(res, error);
+        }
+    });
+    app.patch("/api/workers/:workerId/rename", (req, res) => {
+        try {
+            const displayName = req.body?.displayName;
+            if (typeof displayName !== "string") {
+                throw (0, appError_1.validationError)("Rename request requires a string displayName.", "rename_invalid_payload");
+            }
+            const worker = orchestrator.rename(req.params.workerId, displayName);
+            hub.broadcast({ type: "worker-updated", worker });
+            res.json(worker);
+        }
+        catch (error) {
+            (0, errorResponse_1.handleRequestError)(res, error);
+        }
+    });
+    app.patch("/api/workers/:workerId/movement-mode", (req, res) => {
+        try {
+            const movementMode = req.body?.movementMode;
+            if (movementMode !== "hold" && movementMode !== "wander") {
+                throw (0, appError_1.validationError)("movementMode must be 'hold' or 'wander'.", "movement_mode_invalid_payload");
+            }
+            const worker = orchestrator.setMovementMode(req.params.workerId, movementMode);
+            hub.broadcast({ type: "worker-updated", worker });
+            res.json(worker);
+        }
+        catch (error) {
+            (0, errorResponse_1.handleRequestError)(res, error);
+        }
+    });
+    app.post("/api/workers/:workerId/open-terminal", async (req, res) => {
+        try {
+            await orchestrator.openInExternalTerminal(req.params.workerId);
+            res.json({ ok: true });
+        }
+        catch (error) {
+            (0, errorResponse_1.handleRequestError)(res, error);
+        }
+    });
+    app.post("/api/workers/broadcast-input", async (req, res) => {
+        try {
+            const input = (0, requestParsers_1.parseBroadcastInput)(req.body);
+            const result = await orchestrator.broadcastInput(input.workerIds, input.text, {
+                submit: input.submit
+            });
+            if (result.deliveredWorkerIds.length > 0) {
+                statusMonitor.requestPollSoon();
+            }
+            res.json(result);
+        }
+        catch (error) {
+            (0, errorResponse_1.handleRequestError)(res, error);
+        }
+    });
+}

package/dist/server/server/index.js

@@ -0,0 +1,9 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.bootstrap = void 0;
+const bootstrapApp_1 = require("./bootstrapApp");
+Object.defineProperty(exports, "bootstrap", { enumerable: true, get: function () { return bootstrapApp_1.bootstrap; } });
+void (0, bootstrapApp_1.bootstrap)().catch((error) => {
+    console.error("[arcane-agents] fatal startup error", error);
+    process.exit(1);
+});

package/dist/server/server/orchestrator/orchestratorService.js

@@ -0,0 +1,378 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.OrchestratorService = void 0;
+const nanoid_1 = require("nanoid");
+const node_path_1 = __importDefault(require("node:path"));
+const appError_1 = require("../http/appError");
+const avatarCatalog_1 = require("../assets/avatarCatalog");
+const isSameWorkerRecord_1 = require("./reconcile/isSameWorkerRecord");
+const command_1 = require("./spawn/command");
+const resolveSpawnPlan_1 = require("./spawn/resolveSpawnPlan");
+const avatarAllocator_1 = require("./spawn/avatarAllocator");
+const windowName_1 = require("./spawn/windowName");
+const spawnPosition_1 = require("./spawn/spawnPosition");
+const outpostSpawnSpec = (0, spawnPosition_1.loadOutpostSpawnSpec)();
+const spawnSeparationDistancePx = 52;
+class OrchestratorService {
+    workers;
+    tmux;
+    configuredProjects;
+    discoveredProjects = {};
+    config;
+    constructor(initialConfig, workers, tmux) {
+        this.workers = workers;
+        this.tmux = tmux;
+        this.config = initialConfig;
+        this.configuredProjects = { ...initialConfig.projects };
+    }
+    getConfig() {
+        return this.config;
+    }
+    setDiscoveredProjects(nextDiscovered) {
+        this.discoveredProjects = { ...nextDiscovered };
+        this.refreshConfigProjects();
+        return this.config;
+    }
+    listWorkers() {
+        return this.workers.listWorkers();
+    }
+    getWorker(workerId) {
+        return this.workers.getWorker(workerId);
+    }
+    async spawn(input) {
+        const plan = (0, resolveSpawnPlan_1.resolveSpawnPlan)(this.config, input);
+        const workerId = (0, nanoid_1.nanoid)(8).toLowerCase();
+        const launchCommand = (0, command_1.withClaudeSessionId)(plan.runtimeId, plan.command);
+        const shortId = workerId.slice(0, 4);
+        const windowName = (0, windowName_1.makeWindowName)(plan.project.shortName, plan.runtimeId, shortId);
+        const tmuxRef = await this.tmux.spawnWorker({
+            workerId,
+            windowName,
+            projectPath: plan.project.path,
+            command: launchCommand,
+            projectId: plan.projectId,
+            runtimeId: plan.runtimeId,
+            runtimeLabel: plan.runtime.label
+        });
+        const currentWorkers = this.workers.listWorkers();
+        const spawnAnchorWorkers = this.resolveSpawnAnchorWorkers(input.spawnNearWorkerIds, currentWorkers);
+        const now = new Date().toISOString();
+        const worker = {
+            id: workerId,
+            name: windowName,
+            displayName: plan.displayName,
+            projectId: plan.projectId,
+            projectPath: plan.project.path,
+            runtimeId: plan.runtimeId,
+            runtimeLabel: plan.runtime.label,
+            command: launchCommand,
+            status: "idle",
+            avatarType: this.nextAvatar(plan.avatar, currentWorkers),
+            movementMode: "hold",
+            position: this.nextSpawnPosition(currentWorkers, spawnAnchorWorkers),
+            tmuxRef,
+            createdAt: now,
+            updatedAt: now
+        };
+        this.workers.saveWorker(worker);
+        return worker;
+    }
+    async stop(workerId) {
+        const worker = this.workers.getWorker(workerId);
+        if (!worker) {
+            return {
+                workerId,
+                removed: false,
+                alreadyStopped: true
+            };
+        }
+        try {
+            await this.tmux.stop(worker.tmuxRef);
+        }
+        catch {
+            throw (0, appError_1.conflictError)(`Failed to stop agent '${workerId}'.`, "worker_stop_failed");
+        }
+        const removed = this.workers.deleteWorker(workerId);
+        return {
+            workerId,
+            removed,
+            alreadyStopped: !removed
+        };
+    }
+    updatePosition(workerId, position) {
+        const updated = this.workers.updatePosition(workerId, position);
+        if (!updated) {
+            throw (0, appError_1.notFoundError)(`Agent '${workerId}' not found.`, "worker_not_found");
+        }
+        return updated;
+    }
+    rename(workerId, nextDisplayName) {
+        const worker = this.requireWorker(workerId);
+        const trimmed = nextDisplayName.trim();
+        const updated = {
+            ...worker,
+            displayName: trimmed.length > 0 ? trimmed : undefined,
+            updatedAt: new Date().toISOString()
+        };
+        this.workers.saveWorker(updated);
+        return updated;
+    }
+    setMovementMode(workerId, movementMode) {
+        const updated = this.workers.updateMovementMode(workerId, movementMode);
+        if (!updated) {
+            throw (0, appError_1.notFoundError)(`Agent '${workerId}' not found.`, "worker_not_found");
+        }
+        return updated;
+    }
+    async openInExternalTerminal(workerId) {
+        const worker = this.requireWorker(workerId);
+        try {
+            await this.tmux.openInExternalTerminal(worker.tmuxRef, worker.id);
+        }
+        catch (error) {
+            if (error instanceof Error && error.message.includes("not available")) {
+                throw (0, appError_1.conflictError)(`Agent '${workerId}' is unavailable for external terminal attach.`, "worker_terminal_unavailable");
+            }
+            throw error;
+        }
+    }
+    async broadcastInput(workerIds, text, options) {
+        const uniqueWorkerIds = Array.from(new Set(workerIds));
+        const deliveredWorkerIds = [];
+        const skippedWorkerIds = [];
+        const failed = [];
+        for (const workerId of uniqueWorkerIds) {
+            const worker = this.workers.getWorker(workerId);
+            if (!worker || worker.status === "stopped") {
+                skippedWorkerIds.push(workerId);
+                continue;
+            }
+            try {
+                await this.tmux.sendInput(worker.tmuxRef, text, {
+                    submit: options?.submit
+                });
+                deliveredWorkerIds.push(workerId);
+            }
+            catch (error) {
+                failed.push({
+                    workerId,
+                    error: error instanceof Error ? error.message : "Failed to send input"
+                });
+            }
+        }
+        return {
+            requestedCount: uniqueWorkerIds.length,
+            deliveredWorkerIds,
+            skippedWorkerIds,
+            failed
+        };
+    }
+    async reconcileWithTmux() {
+        const currentWorkers = this.workers.listWorkers();
+        const updatedWorkers = [];
+        const adoptedWorkers = [];
+        const removedWorkerIds = [];
+        const liveManagedWindows = await this.tmux.listManagedWindows();
+        const liveByWorkerId = new Map();
+        const liveByWindow = new Map();
+        const consumedWindows = new Set();
+        for (const liveWindow of liveManagedWindows) {
+            liveByWindow.set(liveWindow.window, liveWindow);
+            if (liveWindow.workerId) {
+                liveByWorkerId.set(liveWindow.workerId, liveWindow);
+            }
+        }
+        for (const worker of currentWorkers) {
+            const liveMatch = liveByWorkerId.get(worker.id) ?? liveByWindow.get(worker.tmuxRef.window);
+            if (!liveMatch) {
+                const directLive = await this.tmux.windowExists(worker.tmuxRef);
+                if (directLive) {
+                    if (worker.status === "stopped") {
+                        const resumed = {
+                            ...worker,
+                            status: "idle",
+                            activityText: undefined,
+                            activityTool: undefined,
+                            activityPath: undefined,
+                            updatedAt: new Date().toISOString()
+                        };
+                        this.workers.saveWorker(resumed);
+                        updatedWorkers.push(resumed);
+                    }
+                    continue;
+                }
+                const removed = this.workers.deleteWorker(worker.id);
+                if (removed) {
+                    removedWorkerIds.push(worker.id);
+                }
+                continue;
+            }
+            consumedWindows.add(liveMatch.window);
+            const projectId = this.resolveProjectId(liveMatch, worker);
+            const runtimeId = this.resolveRuntimeId(liveMatch.runtimeId, worker.runtimeId);
+            const runtimeConfig = this.config.runtimes[runtimeId];
+            const reconciled = {
+                ...worker,
+                name: liveMatch.window,
+                projectId,
+                projectPath: this.resolveProjectPath(liveMatch, projectId, worker.projectPath),
+                runtimeId,
+                runtimeLabel: liveMatch.runtimeLabel ?? runtimeConfig?.label ?? worker.runtimeLabel,
+                command: worker.command,
+                status: worker.status === "stopped" ? "working" : worker.status,
+                tmuxRef: {
+                    session: this.config.backend.tmux.sessionName,
+                    window: liveMatch.window,
+                    pane: liveMatch.pane
+                },
+                updatedAt: new Date().toISOString()
+            };
+            if (!(0, isSameWorkerRecord_1.isSameWorkerRecord)(worker, reconciled)) {
+                this.workers.saveWorker(reconciled);
+                updatedWorkers.push(reconciled);
+            }
+        }
+        for (const liveWindow of liveManagedWindows) {
+            if (consumedWindows.has(liveWindow.window)) {
+                continue;
+            }
+            const workerId = liveWindow.workerId ?? (0, nanoid_1.nanoid)(8).toLowerCase();
+            if (this.workers.getWorker(workerId)) {
+                continue;
+            }
+            const projectId = this.resolveProjectId(liveWindow);
+            const runtimeId = this.resolveRuntimeId(liveWindow.runtimeId);
+            const runtimeConfig = this.config.runtimes[runtimeId];
+            const now = new Date().toISOString();
+            const adopted = {
+                id: workerId,
+                name: liveWindow.window,
+                projectId,
+                projectPath: this.resolveProjectPath(liveWindow, projectId, process.cwd()),
+                runtimeId,
+                runtimeLabel: liveWindow.runtimeLabel ?? runtimeConfig?.label ?? runtimeId,
+                command: runtimeConfig?.command ?? ["bash"],
+                status: "idle",
+                avatarType: this.nextAvatar(),
+                movementMode: "hold",
+                position: this.nextSpawnPosition(),
+                tmuxRef: {
+                    session: this.config.backend.tmux.sessionName,
+                    window: liveWindow.window,
+                    pane: liveWindow.pane
+                },
+                createdAt: now,
+                updatedAt: now
+            };
+            this.workers.saveWorker(adopted);
+            adoptedWorkers.push(adopted);
+        }
+        return {
+            updatedWorkers,
+            adoptedWorkers,
+            removedWorkerIds
+        };
+    }
+    requireWorker(workerId) {
+        const worker = this.workers.getWorker(workerId);
+        if (!worker) {
+            throw (0, appError_1.notFoundError)(`Agent '${workerId}' not found.`, "worker_not_found");
+        }
+        return worker;
+    }
+    resolveProjectId(liveWindow, currentWorker) {
+        if (liveWindow.projectId && this.config.projects[liveWindow.projectId]) {
+            return liveWindow.projectId;
+        }
+        if (currentWorker && this.config.projects[currentWorker.projectId]) {
+            return currentWorker.projectId;
+        }
+        const projectPath = liveWindow.projectPath;
+        if (projectPath) {
+            for (const [projectId, project] of Object.entries(this.config.projects)) {
+                if (project.path === projectPath) {
+                    return projectId;
+                }
+            }
+        }
+        const fallbackPath = projectPath ?? process.cwd();
+        const basename = node_path_1.default.basename(fallbackPath) || "adopted";
+        const baseId = (0, windowName_1.slugify)(liveWindow.projectId ?? basename);
+        let candidate = baseId;
+        let suffix = 2;
+        while (this.config.projects[candidate]) {
+            candidate = `${baseId}-${suffix}`;
+            suffix += 1;
+        }
+        const discoveredProject = {
+            path: fallbackPath,
+            shortName: candidate.slice(0, 8),
+            label: basename,
+            source: "discovered"
+        };
+        this.discoveredProjects[candidate] = discoveredProject;
+        this.refreshConfigProjects();
+        return candidate;
+    }
+    resolveProjectPath(liveWindow, projectId, fallbackPath) {
+        return liveWindow.projectPath ?? this.config.projects[projectId]?.path ?? fallbackPath;
+    }
+    resolveRuntimeId(candidateRuntimeId, fallbackRuntimeId) {
+        if (candidateRuntimeId && this.config.runtimes[candidateRuntimeId]) {
+            return candidateRuntimeId;
+        }
+        if (fallbackRuntimeId && this.config.runtimes[fallbackRuntimeId]) {
+            return fallbackRuntimeId;
+        }
+        if (this.config.runtimes.shell) {
+            return "shell";
+        }
+        const firstRuntimeId = Object.keys(this.config.runtimes)[0];
+        return firstRuntimeId ?? "shell";
+    }
+    nextAvatar(preferred, workers) {
+        return (0, avatarAllocator_1.selectNextAvatar)({
+            preferred,
+            config: this.config,
+            workers: workers ?? this.workers.listWorkers(),
+            availableAvatars: (0, avatarCatalog_1.listAvailableAvatarTypes)()
+        });
+    }
+    nextSpawnPosition(workers, anchorWorkers) {
+        const activeWorkers = (workers ?? this.workers.listWorkers()).filter((worker) => worker.status !== "stopped");
+        return (0, spawnPosition_1.nextSpawnPosition)({
+            activeWorkers,
+            spec: outpostSpawnSpec,
+            spawnSeparationDistancePx,
+            anchorPositions: anchorWorkers?.map((worker) => worker.position)
+        });
+    }
+    resolveSpawnAnchorWorkers(workerIds, workers) {
+        if (!workerIds || workerIds.length === 0) {
+            return [];
+        }
+        const workersById = new Map(workers.map((worker) => [worker.id, worker]));
+        const anchors = [];
+        for (const workerId of workerIds) {
+            const worker = workersById.get(workerId);
+            if (!worker || worker.status === "stopped") {
+                continue;
+            }
+            anchors.push(worker);
+        }
+        return anchors;
+    }
+    refreshConfigProjects() {
+        this.config = {
+            ...this.config,
+            projects: {
+                ...this.configuredProjects,
+                ...this.discoveredProjects
+            }
+        };
+    }
+}
+exports.OrchestratorService = OrchestratorService;

package/dist/server/server/orchestrator/orchestratorService.test.js

@@ -0,0 +1,111 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+const vitest_1 = require("vitest");
+const orchestratorService_1 = require("./orchestratorService");
+function createConfig() {
+    return {
+        projects: {
+            pa: { path: "/tmp/pa", shortName: "pa" }
+        },
+        runtimes: {
+            shell: { command: ["bash"], label: "Shell" }
+        },
+        shortcuts: [],
+        discovery: [],
+        avatars: {
+            disabled: []
+        },
+        audio: {
+            enableSound: true
+        },
+        backend: {
+            tmux: {
+                sessionName: "arcane-agents",
+                pollIntervalMs: 2500
+            }
+        },
+        server: {
+            host: "127.0.0.1",
+            port: 7600
+        }
+    };
+}
+function createWorker() {
+    return {
+        id: "worker-1",
+        name: "worker-1",
+        displayName: "Worker 1",
+        projectId: "pa",
+        projectPath: "/tmp/pa",
+        runtimeId: "shell",
+        runtimeLabel: "Shell",
+        command: ["bash"],
+        status: "idle",
+        avatarType: "wizard",
+        movementMode: "hold",
+        position: { x: 100, y: 100 },
+        tmuxRef: { session: "arcane-agents", window: "worker-1", pane: "%1" },
+        createdAt: "2026-03-04T00:00:00.000Z",
+        updatedAt: "2026-03-04T00:00:00.000Z"
+    };
+}
+(0, vitest_1.describe)("OrchestratorService.stop", () => {
+    (0, vitest_1.it)("stops tmux before removing worker and returns removal result", async () => {
+        const worker = createWorker();
+        const workers = {
+            getWorker: vitest_1.vi.fn(() => worker),
+            deleteWorker: vitest_1.vi.fn(() => true)
+        };
+        const tmux = {
+            stop: vitest_1.vi.fn(async () => undefined)
+        };
+        const service = new orchestratorService_1.OrchestratorService(createConfig(), workers, tmux);
+        const result = await service.stop(worker.id);
+        (0, vitest_1.expect)(result).toEqual({
+            workerId: worker.id,
+            removed: true,
+            alreadyStopped: false
+        });
+        (0, vitest_1.expect)(tmux.stop).toHaveBeenCalledWith(worker.tmuxRef);
+        (0, vitest_1.expect)(workers.deleteWorker).toHaveBeenCalledWith(worker.id);
+        const stopCallOrder = tmux.stop.mock.invocationCallOrder[0] ?? 0;
+        const deleteCallOrder = workers.deleteWorker.mock.invocationCallOrder[0] ?? 0;
+        (0, vitest_1.expect)(stopCallOrder).toBeLessThan(deleteCallOrder);
+    });
+    (0, vitest_1.it)("is idempotent when worker is already missing", async () => {
+        const workers = {
+            getWorker: vitest_1.vi.fn(() => undefined),
+            deleteWorker: vitest_1.vi.fn(() => false)
+        };
+        const tmux = {
+            stop: vitest_1.vi.fn()
+        };
+        const service = new orchestratorService_1.OrchestratorService(createConfig(), workers, tmux);
+        const result = await service.stop("missing-worker");
+        (0, vitest_1.expect)(result).toEqual({
+            workerId: "missing-worker",
+            removed: false,
+            alreadyStopped: true
+        });
+        (0, vitest_1.expect)(tmux.stop).not.toHaveBeenCalled();
+        (0, vitest_1.expect)(workers.deleteWorker).not.toHaveBeenCalled();
+    });
+    (0, vitest_1.it)("keeps worker record when tmux stop fails", async () => {
+        const worker = createWorker();
+        const workers = {
+            getWorker: vitest_1.vi.fn(() => worker),
+            deleteWorker: vitest_1.vi.fn(() => true)
+        };
+        const tmux = {
+            stop: vitest_1.vi.fn(async () => {
+                throw new Error("tmux failure");
+            })
+        };
+        const service = new orchestratorService_1.OrchestratorService(createConfig(), workers, tmux);
+        await (0, vitest_1.expect)(service.stop(worker.id)).rejects.toMatchObject({
+            status: 409,
+            code: "worker_stop_failed"
+        });
+        (0, vitest_1.expect)(workers.deleteWorker).not.toHaveBeenCalled();
+    });
+});

package/dist/server/server/orchestrator/reconcile/isSameWorkerRecord.js

@@ -0,0 +1,17 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.isSameWorkerRecord = isSameWorkerRecord;
+function isSameWorkerRecord(a, b) {
+    return (a.id === b.id &&
+        a.name === b.name &&
+        a.projectId === b.projectId &&
+        a.projectPath === b.projectPath &&
+        a.runtimeId === b.runtimeId &&
+        a.runtimeLabel === b.runtimeLabel &&
+        JSON.stringify(a.command) === JSON.stringify(b.command) &&
+        a.status === b.status &&
+        a.movementMode === b.movementMode &&
+        a.tmuxRef.session === b.tmuxRef.session &&
+        a.tmuxRef.window === b.tmuxRef.window &&
+        a.tmuxRef.pane === b.tmuxRef.pane);
+}

package/dist/server/server/orchestrator/spawn/avatarAllocator.js

@@ -0,0 +1,20 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.selectNextAvatar = selectNextAvatar;
+function selectNextAvatar({ preferred, config, workers, availableAvatars }) {
+    const disabledAvatarTypes = new Set(config.avatars.disabled);
+    const enabledAvailableAvatars = availableAvatars.filter((avatarType) => !disabledAvatarTypes.has(avatarType));
+    if (preferred && enabledAvailableAvatars.includes(preferred)) {
+        return preferred;
+    }
+    const pool = enabledAvailableAvatars.length > 0 ? enabledAvailableAvatars : availableAvatars.length > 0 ? availableAvatars : ["knight"];
+    const reservedConfiguredAvatars = new Set(config.shortcuts
+        .map((shortcut) => shortcut.avatar)
+        .filter((avatarType) => Boolean(avatarType && pool.includes(avatarType))));
+    const randomPool = pool.filter((avatarType) => !reservedConfiguredAvatars.has(avatarType));
+    const eligiblePool = randomPool.length > 0 ? randomPool : pool;
+    const activeAvatars = new Set(workers.filter((worker) => worker.status !== "stopped").map((worker) => worker.avatarType));
+    const unusedAvatars = eligiblePool.filter((avatarType) => !activeAvatars.has(avatarType));
+    const selectionPool = unusedAvatars.length > 0 ? unusedAvatars : eligiblePool;
+    return selectionPool[Math.floor(Math.random() * selectionPool.length)] ?? eligiblePool[0] ?? pool[0] ?? "knight";
+}