@manuelfedele/postino 0.2.0 → 0.3.0

package/dist/index.js

@@ -2,9 +2,9 @@
 import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
 import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
 import { loadConfig } from "./types.js";
-import { connect, disconnect, registerAgent, deregisterAgent } from "./valkey.js";
+import { connect, disconnect, valkey, valkeySub, keys, registerAgent, deregisterAgent } from "./valkey.js";
 import { registerMessagingTools } from "./tools/messaging.js";
-import { startWebServer } from "./web/server.js";
+import { startWebServer, getGuiState, restartOnPort } from "./web/server.js";
 const config = loadConfig();
 const server = new McpServer({
     name: "postino",
@@ -15,6 +15,35 @@ const server = new McpServer({
     },
 });
 registerMessagingTools(server, config.agentName);
+function subscribeGuiTakeover() {
+    const channel = keys.guiTakeoverChannel();
+    valkeySub.subscribe(channel).catch(() => {
+        process.stderr.write("postino: failed to subscribe to GUI takeover channel\n");
+    });
+    valkeySub.on("message", (ch, message) => {
+        if (ch !== channel)
+            return;
+        let data;
+        try {
+            data = JSON.parse(message);
+        }
+        catch {
+            return;
+        }
+        const state = getGuiState();
+        // Skip if we already have a GUI on an equal or lower port
+        if (state.running && state.port !== null && state.port <= data.port)
+            return;
+        // Random jitter (100-500ms) so not all instances race at once
+        const jitter = 100 + Math.random() * 400;
+        setTimeout(async () => {
+            const ok = await restartOnPort(data.port);
+            if (ok) {
+                process.stderr.write(`postino: took over GUI on port ${data.port}\n`);
+            }
+        }, jitter);
+    });
+}
 async function main() {
     try {
         await connect();
@@ -36,9 +65,20 @@ async function main() {
     await server.connect(transport);
     if (config.webEnabled) {
         startWebServer(config.webPort);
+        subscribeGuiTakeover();
     }
     process.stderr.write(`postino agent: ${config.agentName}\n`);
     const shutdown = async () => {
+        // If this instance had a GUI, notify others so they can take over the port
+        const state = getGuiState();
+        if (state.running && state.port !== null) {
+            try {
+                await valkey.publish(keys.guiTakeoverChannel(), JSON.stringify({ port: state.port }));
+            }
+            catch {
+                // Best-effort, connection may already be closing
+            }
+        }
         await deregisterAgent(config.agentName);
         await disconnect();
         process.exit(0);

package/dist/tools/messaging.js

@@ -1,5 +1,5 @@
 import { z } from "zod";
-import { valkey, keys, publishEvent, getOnlineAgents, renameAgent } from "../valkey.js";
+import { valkey, keys, publishEvent, getOnlineAgents, renameAgent, cleanupStaleAgents } from "../valkey.js";
 import { loadConfig } from "../types.js";
 const config = loadConfig();
 // Mutable agent identity so msg_rename can update it
@@ -273,4 +273,23 @@ export function registerMessagingTools(server, initialName) {
                 }],
         };
     });
+    server.registerTool("msg_cleanup", {
+        title: "Cleanup Stale Agents",
+        description: [
+            "Remove offline agents with empty inboxes from the agents list.",
+            "Agents are auto-cleaned on shutdown, but this tool handles stragglers",
+            "(e.g. crashed processes that never ran their shutdown handler).",
+        ].join(" "),
+        inputSchema: {},
+    }, async () => {
+        const removed = await cleanupStaleAgents();
+        return {
+            content: [{
+                    type: "text",
+                    text: removed.length > 0
+                        ? `Removed ${removed.length} stale agent(s): ${removed.join(", ")}`
+                        : "No stale agents to clean up",
+                }],
+        };
+    });
 }

package/dist/valkey.d.ts

@@ -9,11 +9,13 @@ export declare const keys: {
     broadcastCursor: (agent: string) => string;
     notifyChannel: (agent: string) => string;
     eventsChannel: () => string;
+    guiTakeoverChannel: () => string;
 };
 export declare function connect(): Promise<void>;
 export declare function disconnect(): Promise<void>;
 export declare function publishEvent(type: string, data: Record<string, unknown>): Promise<void>;
 export declare function registerAgent(name: string): Promise<void>;
 export declare function deregisterAgent(name: string): Promise<void>;
+export declare function cleanupStaleAgents(): Promise<string[]>;
 export declare function renameAgent(oldName: string, newName: string): Promise<void>;
 export declare function getOnlineAgents(): Promise<string[]>;

package/dist/valkey.js

@@ -20,6 +20,7 @@ export const keys = {
     broadcastCursor: (agent) => `${prefix}bcursor:${agent}`,
     notifyChannel: (agent) => `${prefix}notify:${agent}`,
     eventsChannel: () => `${prefix}events`,
+    guiTakeoverChannel: () => `${prefix}gui:takeover`,
 };
 export async function connect() {
     await valkey.connect();
@@ -60,8 +61,30 @@ export async function deregisterAgent(name) {
     if (heartbeatTimer)
         clearInterval(heartbeatTimer);
     await valkey.del(keys.agentInfo(name));
+    // Auto-cleanup: remove from agents set if inbox is empty
+    const inboxLen = await valkey.llen(keys.inbox(name));
+    if (inboxLen === 0) {
+        await valkey.srem(keys.agents(), name);
+        await valkey.del(keys.broadcastCursor(name));
+    }
     await publishEvent("agent_offline", { agent: name });
 }
+export async function cleanupStaleAgents() {
+    const allAgents = await valkey.smembers(keys.agents());
+    const removed = [];
+    for (const name of allAgents) {
+        const online = await valkey.exists(keys.agentInfo(name));
+        if (online)
+            continue;
+        const inboxLen = await valkey.llen(keys.inbox(name));
+        if (inboxLen === 0) {
+            await valkey.srem(keys.agents(), name);
+            await valkey.del(keys.broadcastCursor(name));
+            removed.push(name);
+        }
+    }
+    return removed;
+}
 export async function renameAgent(oldName, newName) {
     // Stop heartbeat for old name
     if (heartbeatTimer)

package/dist/web/api.js

@@ -1,7 +1,22 @@
 import { Hono } from "hono";
 import { streamSSE } from "hono/streaming";
+import { readFileSync } from "node:fs";
+import { join, dirname } from "node:path";
+import { fileURLToPath } from "node:url";
 import { valkey, valkeySub, keys, publishEvent, getOnlineAgents } from "../valkey.js";
 import { loadConfig } from "../types.js";
+const __dirname = dirname(fileURLToPath(import.meta.url));
+function readVersion() {
+    try {
+        const pkgPath = join(__dirname, "..", "package.json");
+        const pkg = JSON.parse(readFileSync(pkgPath, "utf-8"));
+        return pkg.version || "0.0.0";
+    }
+    catch {
+        return "0.0.0";
+    }
+}
+const VERSION = readVersion();
 const config = loadConfig();
 export const api = new Hono();
 // --- Agents ---
@@ -80,7 +95,7 @@ api.get("/stats", async (c) => {
         messageCount += await valkey.llen(keys.inbox(a));
     }
     const broadcastCount = await valkey.llen(keys.broadcasts());
-    return c.json({ agentCount: agents.length, messageCount, broadcastCount });
+    return c.json({ version: VERSION, agentCount: agents.length, messageCount, broadcastCount });
 });
 // --- Agent-specific check (for hooks, zero-token) ---
 api.get("/check/:agent", async (c) => {
@@ -101,7 +116,9 @@ function ensureEventSubscription() {
     valkeySub.subscribe(keys.eventsChannel()).catch(() => {
         subscribedToEvents = false;
     });
-    valkeySub.on("message", (_channel, message) => {
+    valkeySub.on("message", (channel, message) => {
+        if (channel !== keys.eventsChannel())
+            return;
         for (const client of sseClients) {
             try {
                 client.send(message);

package/dist/web/public/index.html

@@ -141,7 +141,7 @@
   <div class="topbar">
     <div class="logo">
       <h1>postino</h1>
-      <span class="pill pill-muted">v0.1.0</span>
+      <span class="pill pill-muted" id="version"></span>
       <span class="pill pill-accent" id="agent-id"></span>
     </div>
     <div class="meta">
@@ -288,7 +288,7 @@ function connectSSE(){
   es.onerror=()=>{d.className='dot dot-off';t.textContent='reconnecting'};
 }
 
-async function loadStats(){const s=await api('/stats');if(!s)return;document.getElementById('stat-agents').textContent=s.agentCount+' agents';document.getElementById('stat-msg').textContent=s.messageCount+' msg';document.getElementById('stat-bc').textContent=s.broadcastCount+' bc'}
+async function loadStats(){const s=await api('/stats');if(!s)return;document.getElementById('version').textContent='v'+s.version;document.getElementById('stat-agents').textContent=s.agentCount+' agents';document.getElementById('stat-msg').textContent=s.messageCount+' msg';document.getElementById('stat-bc').textContent=s.broadcastCount+' bc'}
 
 function esc(s){if(!s)return'';const d=document.createElement('div');d.textContent=s;return d.innerHTML}
 function fmtT(i){try{const d=new Date(i),n=new Date();return d.toDateString()===n.toDateString()?d.toLocaleTimeString([],{hour:'2-digit',minute:'2-digit'}):d.toLocaleDateString([],{month:'short',day:'numeric'})+' '+d.toLocaleTimeString([],{hour:'2-digit',minute:'2-digit'})}catch{return i}}

package/dist/web/server.d.ts

@@ -1 +1,7 @@
+export interface GuiState {
+    running: boolean;
+    port: number | null;
+}
+export declare function getGuiState(): GuiState;
 export declare function startWebServer(port: number, attempt?: number): void;
+export declare function restartOnPort(port: number): Promise<boolean>;

package/dist/web/server.js

@@ -49,9 +49,16 @@ app.get("/", (c) => {
     return c.html(html);
 });
 const MAX_PORT_ATTEMPTS = 10;
+let currentServer = null;
+let currentPort = null;
+export function getGuiState() {
+    return { running: currentServer !== null, port: currentPort };
+}
 export function startWebServer(port, attempt = 0) {
     try {
         const server = serve({ fetch: app.fetch, port }, () => {
+            currentServer = server;
+            currentPort = port;
             process.stderr.write(`postino GUI: http://localhost:${port}\n`);
         });
         server.on("error", (err) => {
@@ -69,3 +76,33 @@ export function startWebServer(port, attempt = 0) {
         process.stderr.write(`postino GUI failed to start: ${err}\n`);
     }
 }
+export function restartOnPort(port) {
+    return new Promise((resolve) => {
+        try {
+            const server = serve({ fetch: app.fetch, port }, () => {
+                // New server started successfully, close the old one
+                const oldServer = currentServer;
+                currentServer = server;
+                currentPort = port;
+                process.stderr.write(`postino GUI: takeover http://localhost:${port}\n`);
+                if (oldServer) {
+                    oldServer.close();
+                }
+                resolve(true);
+            });
+            server.on("error", (err) => {
+                if (err.code === "EADDRINUSE") {
+                    process.stderr.write(`postino: takeover port ${port} already claimed\n`);
+                }
+                else {
+                    process.stderr.write(`postino: takeover failed: ${err.message}\n`);
+                }
+                // Old server stays running, state unchanged
+                resolve(false);
+            });
+        }
+        catch {
+            resolve(false);
+        }
+    });
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@manuelfedele/postino",
-  "version": "0.2.0",
+  "version": "0.3.0",
   "description": "Inter-agent messaging and broadcast system for Claude Code",
   "type": "module",
   "main": "dist/index.js",