@cydm/magic-shell-agent-node 0.1.0

package/dist/worker-registry.js

@@ -0,0 +1,501 @@
+const DEFAULT_WORKER_NAMES = ["Alpha", "Bravo", "Charlie", "Delta", "Echo", "Falcon", "Nova", "Scout"];
+export class WorkerRegistry {
+    workers = new Map();
+    sessionToAgent = new Map();
+    recentEvents = new Map();
+    snapshots = new Map();
+    maxRecentEvents = 24;
+    maxSnapshots = 16;
+    allocateDisplayName() {
+        const used = new Set(Array.from(this.workers.values())
+            .map((worker) => worker.displayName)
+            .filter((value) => !!value));
+        for (const name of DEFAULT_WORKER_NAMES) {
+            if (!used.has(name)) {
+                return name;
+            }
+        }
+        return `worker-${this.workers.size + 1}`;
+    }
+    createWorkerRecord(options) {
+        const record = {
+            agentId: options.agentId,
+            agentType: options.plugin.name,
+            role: "worker",
+            sessionId: options.sessionId,
+            nodeId: options.nodeId,
+            parentAgentId: options.parentAgentId,
+            cwd: options.cwd || options.plugin.cwd || process.cwd(),
+            displayName: options.displayName || this.allocateDisplayName(),
+            taskSummary: options.taskSummary || "",
+            status: "starting",
+            phase: "booting",
+            attachEndpoint: {
+                kind: "session",
+                sessionId: options.sessionId,
+            },
+            controlEndpoint: {
+                kind: "local",
+                sessionId: options.sessionId,
+            },
+            createdAt: Date.now(),
+            activityUpdatedAt: Date.now(),
+            attachCount: 0,
+            restartCount: 0,
+            inspectCount: 0,
+            outputEventCount: 0,
+            outputCharCount: 0,
+            totalRunMs: 0,
+            capabilities: [...options.plugin.capabilities],
+        };
+        this.workers.set(record.agentId, record);
+        this.sessionToAgent.set(record.sessionId, record.agentId);
+        this.appendEvent(record.agentId, {
+            type: "spawned",
+            timestamp: Date.now(),
+            message: `${record.agentType} launched in ${record.cwd}`,
+        });
+        return record;
+    }
+    rebindWorkerSession(existingAgentId, options) {
+        const existing = this.workers.get(existingAgentId);
+        if (!existing)
+            return undefined;
+        if (existingAgentId !== options.agentId) {
+            this.workers.delete(existingAgentId);
+            const existingEvents = this.recentEvents.get(existingAgentId) || [];
+            const existingSnapshots = this.snapshots.get(existingAgentId) || [];
+            this.recentEvents.delete(existingAgentId);
+            this.snapshots.delete(existingAgentId);
+            this.recentEvents.set(options.agentId, existingEvents);
+            this.snapshots.set(options.agentId, existingSnapshots);
+        }
+        const next = {
+            ...existing,
+            agentId: options.agentId,
+            agentType: options.plugin.name,
+            nodeId: options.nodeId,
+            parentAgentId: options.parentAgentId,
+            cwd: options.cwd || options.plugin.cwd || existing.cwd,
+            displayName: options.displayName || existing.displayName,
+            taskSummary: options.taskSummary || existing.taskSummary,
+            status: "starting",
+            attachEndpoint: {
+                kind: "session",
+                sessionId: options.sessionId,
+            },
+            controlEndpoint: {
+                kind: "local",
+                sessionId: options.sessionId,
+            },
+            capabilities: [...options.plugin.capabilities],
+            startedAt: undefined,
+            lastAttachedAt: undefined,
+            stoppedAt: undefined,
+            exitCode: undefined,
+            lastError: undefined,
+            outputEventCount: existing.outputEventCount || 0,
+            outputCharCount: existing.outputCharCount || 0,
+            lastEventAt: undefined,
+            lastEventSummary: undefined,
+        };
+        this.workers.set(options.agentId, next);
+        this.sessionToAgent.set(options.sessionId, options.agentId);
+        this.appendEvent(options.agentId, {
+            type: "restarted",
+            timestamp: Date.now(),
+            message: `${next.agentType} relaunched in ${next.cwd}`,
+        });
+        return next;
+    }
+    getWorkerByAgentId(agentId) {
+        return this.refreshWorkerState(agentId);
+    }
+    getWorkerBySessionId(sessionId) {
+        const agentId = this.sessionToAgent.get(sessionId);
+        return agentId ? this.refreshWorkerState(agentId) : undefined;
+    }
+    listWorkers() {
+        return this.refreshAllWorkerStates().sort((a, b) => a.createdAt - b.createdAt);
+    }
+    updateWorker(agentId, updates) {
+        const existing = this.workers.get(agentId);
+        if (!existing)
+            return undefined;
+        const next = this.deriveWorkerState({ ...existing, ...updates });
+        this.workers.set(agentId, next);
+        this.captureSnapshot(existing, next);
+        return next;
+    }
+    getWorkerDetail(agentId, lastBufferedOutput) {
+        const worker = this.getWorkerByAgentId(agentId);
+        if (!worker)
+            return undefined;
+        return {
+            worker,
+            pluginName: worker.agentType,
+            lastBufferedOutput,
+            recentEvents: [...(this.recentEvents.get(agentId) || [])],
+            snapshots: [...(this.snapshots.get(agentId) || [])],
+        };
+    }
+    getRuntimeSummary() {
+        const workers = this.listWorkers();
+        const liveWorkers = workers.filter((worker) => worker.status !== "stopped" && worker.status !== "failed");
+        const busyWorkers = liveWorkers.filter((worker) => worker.activityState === "busy").length;
+        const waitingWorkers = liveWorkers.filter((worker) => worker.activityState === "ready").length;
+        const quietWorkers = liveWorkers.filter((worker) => worker.phase === "quiet").length;
+        const attentionWorkers = liveWorkers.filter((worker) => this.workerNeedsAttention(worker)).length;
+        const failedWorkers = workers.filter((worker) => worker.status === "failed").length;
+        const watchWorkers = liveWorkers.filter((worker) => worker.interventionLevel === "watch").length;
+        const suggestedWorkers = liveWorkers.filter((worker) => worker.interventionLevel === "suggested").length;
+        const requiredWorkers = workers.filter((worker) => worker.interventionLevel === "required").length;
+        const observeWorkers = liveWorkers.filter((worker) => worker.recommendedAction === "observe").length;
+        const attachWorkers = liveWorkers.filter((worker) => worker.recommendedAction === "attach").length;
+        const restartWorkers = workers.filter((worker) => worker.recommendedAction === "restart").length;
+        const closeWorkers = workers.filter((worker) => worker.recommendedAction === "close").length;
+        const totalRestarts = workers.reduce((sum, worker) => sum + (worker.restartCount || 0), 0);
+        const totalAttaches = workers.reduce((sum, worker) => sum + (worker.attachCount || 0), 0);
+        const totalOutputChars = workers.reduce((sum, worker) => sum + (worker.outputCharCount || 0), 0);
+        const lastUpdatedAt = workers.reduce((latest, worker) => Math.max(latest, worker.lastEventAt || 0, worker.lastOutputAt || 0, worker.activityUpdatedAt || 0, worker.stoppedAt || 0, worker.startedAt || 0, worker.createdAt || 0), 0);
+        return {
+            totalWorkers: workers.length,
+            liveWorkers: liveWorkers.length,
+            closedWorkers: workers.length - liveWorkers.length,
+            busyWorkers,
+            waitingWorkers,
+            quietWorkers,
+            attentionWorkers,
+            failedWorkers,
+            watchWorkers,
+            suggestedWorkers,
+            requiredWorkers,
+            observeWorkers,
+            attachWorkers,
+            restartWorkers,
+            closeWorkers,
+            totalRestarts,
+            totalAttaches,
+            totalOutputChars,
+            lastUpdatedAt,
+        };
+    }
+    getRuntimeFocus(limit = 5) {
+        const priority = (worker) => {
+            switch (worker.recommendedAction) {
+                case "restart":
+                    return 5;
+                case "attach":
+                    return worker.interventionLevel === "required" ? 4 : 3;
+                case "observe":
+                    return worker.interventionLevel === "watch" ? 2 : 1;
+                case "close":
+                    return 0;
+                default:
+                    return -1;
+            }
+        };
+        return this.listWorkers()
+            .filter((worker) => worker.recommendedAction && worker.recommendedAction !== "none")
+            .sort((a, b) => {
+            const byPriority = priority(b) - priority(a);
+            if (byPriority !== 0)
+                return byPriority;
+            return (b.lastEventAt || b.activityUpdatedAt || b.lastOutputAt || b.createdAt)
+                - (a.lastEventAt || a.activityUpdatedAt || a.lastOutputAt || a.createdAt);
+        })
+            .slice(0, limit)
+            .map((worker) => ({
+            agentId: worker.agentId,
+            sessionId: worker.sessionId,
+            title: worker.displayName || worker.taskSummary || worker.agentSessionId || `S:${worker.sessionId.slice(-6)}`,
+            displayName: worker.displayName,
+            agentType: worker.agentType,
+            coordinationState: worker.coordinationState,
+            phase: worker.phase,
+            interventionLevel: worker.interventionLevel,
+            recommendedAction: worker.recommendedAction,
+            reason: worker.recommendedActionReason || worker.interventionReason || worker.attentionReason || worker.lastEventSummary,
+            updatedAt: worker.lastEventAt || worker.activityUpdatedAt || worker.lastOutputAt || worker.createdAt,
+        }));
+    }
+    updateWorkerStatus(agentId, status, details = {}) {
+        const updates = { ...details, status };
+        if (status === "running" && updates.startedAt === undefined) {
+            updates.startedAt = Date.now();
+        }
+        if ((status === "stopped" || status === "failed") && updates.stoppedAt === undefined) {
+            updates.stoppedAt = Date.now();
+        }
+        const next = this.updateWorker(agentId, updates);
+        if (next) {
+            if ((status === "stopped" || status === "failed") && next.startedAt) {
+                const totalRunMs = (next.totalRunMs || 0) + Math.max(0, Date.now() - next.startedAt);
+                this.updateWorker(agentId, { totalRunMs });
+            }
+            this.appendEvent(agentId, {
+                type: status === "stopped" ? "stopped" : "state_changed",
+                timestamp: Date.now(),
+                message: `status -> ${status}`,
+            });
+        }
+        return next;
+    }
+    removeWorker(agentId) {
+        const worker = this.workers.get(agentId);
+        if (!worker)
+            return false;
+        this.sessionToAgent.delete(worker.sessionId);
+        return this.workers.delete(agentId);
+    }
+    recordOutput(sessionId) {
+        const worker = this.getWorkerBySessionId(sessionId);
+        if (!worker)
+            return undefined;
+        return this.recordOutputActivity(worker.agentId, 0);
+    }
+    recordOutputActivity(agentId, charCount) {
+        const worker = this.getWorkerByAgentId(agentId);
+        if (!worker)
+            return undefined;
+        return this.updateWorker(worker.agentId, {
+            lastOutputAt: Date.now(),
+            status: worker.status === "starting" ? "running" : worker.status,
+            outputEventCount: (worker.outputEventCount || 0) + 1,
+            outputCharCount: (worker.outputCharCount || 0) + Math.max(0, charCount),
+        });
+    }
+    recordEvent(agentId, event) {
+        this.appendEvent(agentId, event);
+    }
+    appendEvent(agentId, event) {
+        const normalizedEvent = this.normalizeEvent(event);
+        const next = [...(this.recentEvents.get(agentId) || []), normalizedEvent].slice(-this.maxRecentEvents);
+        this.recentEvents.set(agentId, next);
+        const worker = this.workers.get(agentId);
+        if (worker) {
+            const updates = {
+                lastEventAt: normalizedEvent.timestamp,
+                lastEventSummary: this.summarizeEvent(normalizedEvent.message),
+                lastEventLevel: normalizedEvent.level,
+            };
+            if (normalizedEvent.type === "attached") {
+                updates.attachCount = (worker.attachCount || 0) + 1;
+                updates.lastAttachedAt = normalizedEvent.timestamp;
+            }
+            if (normalizedEvent.type === "restarted") {
+                updates.restartCount = (worker.restartCount || 0) + 1;
+            }
+            if (normalizedEvent.type === "inspected") {
+                updates.inspectCount = (worker.inspectCount || 0) + 1;
+            }
+            this.workers.set(agentId, {
+                ...worker,
+                ...updates,
+            });
+        }
+    }
+    summarizeEvent(message) {
+        return message.replace(/\s+/g, " ").trim().slice(0, 96);
+    }
+    normalizeEvent(event) {
+        return {
+            ...event,
+            level: event.level || this.inferEventLevel(event),
+        };
+    }
+    inferEventLevel(event) {
+        switch (event.type) {
+            case "spawned":
+            case "attached":
+            case "restarted":
+            case "inspected":
+                return "control";
+            case "error":
+                return "error";
+            case "stopped":
+                return "warning";
+            default:
+                return "info";
+        }
+    }
+    captureSnapshot(previous, next) {
+        const changed = previous.status !== next.status
+            || previous.phase !== next.phase
+            || previous.activityState !== next.activityState
+            || previous.interventionLevel !== next.interventionLevel;
+        if (!changed)
+            return;
+        const snapshot = {
+            timestamp: Date.now(),
+            status: next.status,
+            phase: next.phase,
+            activityState: next.activityState,
+            interventionLevel: next.interventionLevel,
+            summary: this.summarizeSnapshot(next),
+        };
+        const history = [...(this.snapshots.get(next.agentId) || []), snapshot].slice(-this.maxSnapshots);
+        this.snapshots.set(next.agentId, history);
+    }
+    summarizeSnapshot(worker) {
+        const parts = [worker.status];
+        if (worker.coordinationState && worker.coordinationState !== "idle")
+            parts.push(worker.coordinationState);
+        if (worker.phase)
+            parts.push(worker.phase);
+        if (worker.activityState)
+            parts.push(worker.activityState);
+        if (worker.interventionLevel && worker.interventionLevel !== "none") {
+            parts.push(worker.interventionLevel);
+        }
+        return parts.join(" · ");
+    }
+    workerNeedsAttention(worker) {
+        if (worker.status === "blocked" || worker.status === "failed")
+            return true;
+        if (worker.activityState !== "busy" || !worker.activityUpdatedAt || !worker.lastOutputAt)
+            return false;
+        return (Date.now() - worker.activityUpdatedAt) > 90_000 && (Date.now() - worker.lastOutputAt) > 45_000;
+    }
+    deriveWorkerState(worker) {
+        const now = Date.now();
+        let phase = worker.phase;
+        let activityState = worker.activityState;
+        let attentionReason = undefined;
+        let interventionLevel = "none";
+        let interventionReason = undefined;
+        let recommendedAction = "none";
+        let recommendedActionReason = undefined;
+        if (worker.status === "starting" || worker.status === "stopping") {
+            phase = "booting";
+        }
+        else if (worker.status === "stopped" || worker.status === "failed") {
+            phase = "closed";
+            if (worker.status === "failed") {
+                attentionReason = worker.lastError || "worker failed";
+                interventionLevel = "required";
+                interventionReason = attentionReason;
+                recommendedAction = "restart";
+                recommendedActionReason = "worker failed";
+            }
+            else {
+                recommendedAction = "close";
+                recommendedActionReason = "worker already stopped";
+            }
+        }
+        else if (worker.status === "blocked") {
+            phase = "attention";
+            attentionReason = worker.lastError || "worker reported blocked";
+            interventionLevel = "required";
+            interventionReason = attentionReason;
+            recommendedAction = "attach";
+            recommendedActionReason = attentionReason;
+        }
+        else if (this.workerNeedsAttention(worker)) {
+            phase = "attention";
+            attentionReason = "busy for a while without fresh output";
+            interventionLevel = "suggested";
+            interventionReason = attentionReason;
+            recommendedAction = "attach";
+            recommendedActionReason = attentionReason;
+        }
+        else if (worker.coordinationState === "delegating" || worker.coordinationState === "waiting_for_result") {
+            phase = "working";
+            activityState = "busy";
+            recommendedAction = "observe";
+            recommendedActionReason = worker.coordinationTaskSummary
+                ? `delegated turn in progress: ${worker.coordinationTaskSummary}`
+                : "delegated turn in progress";
+        }
+        else if (worker.coordinationState === "result_received" || worker.coordinationState === "integrating_result") {
+            phase = "waiting";
+            activityState = "ready";
+            recommendedAction = "observe";
+            recommendedActionReason = "delegated turn completed";
+        }
+        else if (worker.activityState === "busy") {
+            phase = "working";
+            recommendedAction = "observe";
+            recommendedActionReason = "worker is actively working";
+        }
+        else if (worker.activityState === "ready") {
+            const outputAgeMs = worker.lastOutputAt ? now - worker.lastOutputAt : null;
+            if (outputAgeMs !== null && outputAgeMs > 600_000) {
+                phase = "quiet";
+                interventionLevel = "watch";
+                interventionReason = "quiet for a while";
+                recommendedAction = "observe";
+                recommendedActionReason = "worker has been quiet for a while";
+            }
+            else {
+                phase = "waiting";
+                recommendedAction = "attach";
+                recommendedActionReason = "worker appears ready for input";
+            }
+        }
+        else if (worker.lastOutputAt && (now - worker.lastOutputAt) < 45_000) {
+            phase = "working";
+            recommendedAction = "observe";
+            recommendedActionReason = "worker has recent activity";
+        }
+        else if (worker.lastOutputAt && (now - worker.lastOutputAt) > 600_000) {
+            phase = "quiet";
+            interventionLevel = "watch";
+            interventionReason = "quiet for a while";
+            recommendedAction = "observe";
+            recommendedActionReason = "worker has been idle for a while";
+        }
+        else {
+            phase = "waiting";
+            recommendedAction = "attach";
+            recommendedActionReason = "worker is waiting";
+        }
+        let interventionSince = undefined;
+        if (interventionLevel && interventionLevel !== "none") {
+            interventionSince = worker.interventionLevel === interventionLevel
+                ? worker.interventionSince || now
+                : now;
+        }
+        return {
+            ...worker,
+            activityState,
+            phase,
+            attentionReason,
+            interventionLevel,
+            interventionReason,
+            interventionSince,
+            recommendedAction,
+            recommendedActionReason,
+        };
+    }
+    refreshAllWorkerStates() {
+        const refreshed = [];
+        for (const worker of this.workers.values()) {
+            refreshed.push(this.refreshWorkerState(worker.agentId) || worker);
+        }
+        return refreshed;
+    }
+    refreshWorkerState(agentId) {
+        const existing = this.workers.get(agentId);
+        if (!existing)
+            return undefined;
+        const next = this.deriveWorkerState(existing);
+        if (this.hasDerivedStateChanged(existing, next)) {
+            this.workers.set(agentId, next);
+            this.captureSnapshot(existing, next);
+            return next;
+        }
+        return existing;
+    }
+    hasDerivedStateChanged(previous, next) {
+        return previous.status !== next.status
+            || previous.phase !== next.phase
+            || previous.activityState !== next.activityState
+            || previous.attentionReason !== next.attentionReason
+            || previous.interventionLevel !== next.interventionLevel
+            || previous.interventionReason !== next.interventionReason
+            || previous.interventionSince !== next.interventionSince
+            || previous.recommendedAction !== next.recommendedAction
+            || previous.recommendedActionReason !== next.recommendedActionReason;
+    }
+}

package/dist/worker-runtime.d.ts

@@ -0,0 +1,18 @@
+import type { PluginConfig, ServerMessage } from "./types.js";
+import type { SessionManager } from "./session-manager.js";
+import type { WorkerRegistry } from "./worker-registry.js";
+export interface SpawnWorkerRuntimeOptions {
+    sessionId: string;
+    pluginName: string;
+    cwd?: string;
+    displayName?: string;
+    taskSummary?: string;
+    parentAgentId?: string;
+}
+export interface SpawnWorkerRuntimeDeps {
+    nodeId: string;
+    plugins: Map<string, PluginConfig>;
+    sessionManager: SessionManager;
+    workerRegistry: WorkerRegistry;
+}
+export declare function spawnManagedWorker(options: SpawnWorkerRuntimeOptions, deps: SpawnWorkerRuntimeDeps): Promise<ServerMessage>;

package/dist/worker-runtime.js

@@ -0,0 +1,69 @@
+import os from "node:os";
+import path from "node:path";
+function normalizeWorkerCwd(cwd, pluginCwd) {
+    const value = (cwd || pluginCwd || "").trim();
+    if (!value)
+        return undefined;
+    if (value === "~") {
+        return os.homedir();
+    }
+    if (value.startsWith("~/")) {
+        return path.join(os.homedir(), value.slice(2));
+    }
+    if (path.isAbsolute(value)) {
+        return value;
+    }
+    return path.resolve(pluginCwd || process.cwd(), value);
+}
+export async function spawnManagedWorker(options, deps) {
+    const plugin = deps.plugins.get(options.pluginName);
+    if (!plugin) {
+        throw new Error(`Plugin not found: ${options.pluginName}`);
+    }
+    const runtimePlugin = {
+        ...plugin,
+        args: plugin.name === "pie"
+            ? [...(plugin.args || []), "--session-id", options.sessionId]
+            : plugin.args,
+        cwd: normalizeWorkerCwd(options.cwd, plugin.cwd),
+    };
+    await deps.sessionManager.createSession(options.sessionId, runtimePlugin);
+    const session = deps.sessionManager.getSession(options.sessionId);
+    if (!session) {
+        throw new Error(`Session failed to start: ${options.sessionId}`);
+    }
+    const existing = deps.workerRegistry.getWorkerBySessionId(options.sessionId);
+    if (!existing) {
+        deps.workerRegistry.createWorkerRecord({
+            agentId: session.agentId,
+            sessionId: options.sessionId,
+            nodeId: deps.nodeId,
+            plugin: runtimePlugin,
+            cwd: runtimePlugin.cwd,
+            displayName: options.displayName,
+            taskSummary: options.taskSummary,
+            parentAgentId: options.parentAgentId,
+        });
+    }
+    else {
+        deps.workerRegistry.rebindWorkerSession(existing.agentId, {
+            agentId: session.agentId,
+            sessionId: options.sessionId,
+            nodeId: deps.nodeId,
+            plugin: runtimePlugin,
+            cwd: runtimePlugin.cwd,
+            displayName: existing.displayName,
+            taskSummary: existing.taskSummary,
+            parentAgentId: existing.parentAgentId,
+        });
+    }
+    deps.workerRegistry.updateWorkerStatus(session.agentId, "running", {
+        startedAt: Date.now(),
+    });
+    return {
+        type: "session",
+        sessionId: options.sessionId,
+        agentType: runtimePlugin.name,
+        capabilities: runtimePlugin.capabilities,
+    };
+}

package/dist/ws-client.d.ts

@@ -0,0 +1,68 @@
+import type { ClientMessage, ServerMessage } from "@cydm/magic-shell-protocol";
+export interface WebSocketClientOptions {
+    url: string;
+    nodeId: string;
+    password: string;
+    autoReconnect?: boolean;
+    reconnectDelay?: number;
+    maxReconnectDelay?: number;
+}
+type MessageHandler = (message: ServerMessage | ClientMessage) => void;
+type StatusHandler = (status: "connected" | "disconnected" | "error", error?: Error) => void;
+/**
+ * WebSocket 客户端
+ * 负责与 Relay Server 保持连接，自动重连
+ */
+export declare class WebSocketClient {
+    private options;
+    private ws?;
+    private messageHandlers;
+    private statusHandlers;
+    private reconnectAttempts;
+    private reconnectTimer?;
+    private isConnected;
+    private isConnecting;
+    private manualDisconnect;
+    constructor(options: WebSocketClientOptions);
+    /**
+     * 连接到 Relay Server
+     */
+    connect(): Promise<void>;
+    /**
+     * 断开连接
+     */
+    disconnect(): void;
+    /**
+     * 发送消息
+     */
+    send(message: ClientMessage | ServerMessage): void;
+    /**
+     * 注册消息处理器
+     */
+    onMessage(handler: MessageHandler): void;
+    /**
+     * 注册状态处理器
+     */
+    onStatus(handler: StatusHandler): void;
+    /**
+     * 获取连接状态
+     */
+    getStatus(): "connected" | "disconnected" | "connecting";
+    /**
+     * 处理断开连接
+     */
+    private handleDisconnect;
+    /**
+     * 安排重连
+     */
+    private scheduleReconnect;
+    /**
+     * 触发消息事件
+     */
+    private emitMessage;
+    /**
+     * 触发状态事件
+     */
+    private emitStatus;
+}
+export {};