@manuelfedele/postino 0.1.0

package/dist/tools/messaging.js

@@ -0,0 +1,276 @@
+import { z } from "zod";
+import { valkey, keys, publishEvent, getOnlineAgents, renameAgent } from "../valkey.js";
+import { loadConfig } from "../types.js";
+const config = loadConfig();
+// Mutable agent identity so msg_rename can update it
+const identity = { name: "" };
+export function registerMessagingTools(server, initialName) {
+    identity.name = initialName;
+    server.registerTool("msg_whoami", {
+        title: "Status Overview",
+        description: [
+            "Get a full status overview: your identity, unread messages, unseen broadcasts, and all online agents.",
+            "Call this at the start of a session to orient yourself.",
+            "Returns everything you need in one call, no need to call msg_check or msg_list_agents separately.",
+        ].join(" "),
+        inputSchema: {},
+    }, async () => {
+        // Unread messages
+        const unread = await valkey.llen(keys.inbox(identity.name));
+        // Unseen broadcasts
+        const allBc = await valkey.lrange(keys.broadcasts(), 0, -1);
+        const cursorStr = await valkey.get(keys.broadcastCursor(identity.name));
+        const cursor = cursorStr ? parseInt(cursorStr, 10) : 0;
+        const unseenBc = allBc.length - cursor;
+        // Online agents
+        const allAgents = await valkey.smembers(keys.agents());
+        const onlineSet = new Set(await getOnlineAgents());
+        const agentList = [];
+        for (const name of allAgents.sort()) {
+            const msgCount = await valkey.llen(keys.inbox(name));
+            agentList.push({
+                name,
+                online: onlineSet.has(name),
+                messages: msgCount,
+                isMe: name === identity.name,
+            });
+        }
+        const status = {
+            me: identity.name,
+            unreadMessages: unread,
+            unseenBroadcasts: Math.max(0, unseenBc),
+            totalBroadcasts: allBc.length,
+            agents: agentList,
+        };
+        return {
+            content: [{
+                    type: "text",
+                    text: JSON.stringify(status, null, 2),
+                }],
+        };
+    });
+    server.registerTool("msg_rename", {
+        title: "Rename Agent",
+        description: [
+            "Rename this agent to a meaningful name (e.g. 'devops-agent', 'frontend-dev', 'reviewer').",
+            "This moves your inbox and updates your identity across the system.",
+            "Other agents will see your new name immediately.",
+        ].join(" "),
+        inputSchema: {
+            name: z.string().describe("New agent name (e.g. 'devops-agent', 'code-reviewer')"),
+        },
+    }, async ({ name }) => {
+        const oldName = identity.name;
+        if (name === oldName) {
+            return {
+                content: [{ type: "text", text: `Already named "${name}"` }],
+            };
+        }
+        // Check if name is taken by an online agent
+        const online = await getOnlineAgents();
+        if (online.includes(name)) {
+            return {
+                content: [{ type: "text", text: `Name "${name}" is taken by an online agent` }],
+                isError: true,
+            };
+        }
+        await renameAgent(oldName, name);
+        identity.name = name;
+        return {
+            content: [{ type: "text", text: `Renamed from "${oldName}" to "${name}"` }],
+        };
+    });
+    server.registerTool("msg_list_agents", {
+        title: "List Agents",
+        description: [
+            "List all known agents and their status.",
+            "Shows which agents are currently online (have an active MCP server running)",
+            "and how many messages are in each agent's inbox.",
+            "Use this to discover who you can send messages to.",
+        ].join(" "),
+        inputSchema: {},
+    }, async () => {
+        const allAgents = await valkey.smembers(keys.agents());
+        const onlineSet = new Set(await getOnlineAgents());
+        const result = [];
+        for (const name of allAgents.sort()) {
+            const msgCount = await valkey.llen(keys.inbox(name));
+            result.push({
+                name,
+                online: onlineSet.has(name),
+                messages: msgCount,
+                isMe: name === identity.name,
+            });
+        }
+        return {
+            content: [{
+                    type: "text",
+                    text: result.length > 0
+                        ? JSON.stringify(result, null, 2)
+                        : "No agents registered yet. Send a message to create an inbox.",
+                }],
+        };
+    });
+    server.registerTool("msg_check", {
+        title: "Check for New Activity",
+        description: [
+            "Quick check for new messages and broadcasts without consuming them.",
+            "Returns unread message count and unseen broadcast count.",
+            "Use this to decide whether to call msg_read or msg_broadcasts.",
+        ].join(" "),
+        inputSchema: {},
+    }, async () => {
+        const msgCount = await valkey.llen(keys.inbox(identity.name));
+        const allBc = await valkey.lrange(keys.broadcasts(), 0, -1);
+        const cursorStr = await valkey.get(keys.broadcastCursor(identity.name));
+        const cursor = cursorStr ? parseInt(cursorStr, 10) : 0;
+        const unseenBc = Math.max(0, allBc.length - cursor);
+        const parts = [];
+        if (msgCount > 0)
+            parts.push(`${msgCount} unread message${msgCount !== 1 ? "s" : ""}`);
+        if (unseenBc > 0)
+            parts.push(`${unseenBc} unseen broadcast${unseenBc !== 1 ? "s" : ""}`);
+        return {
+            content: [{
+                    type: "text",
+                    text: parts.length > 0
+                        ? parts.join(", ")
+                        : "No new messages or broadcasts",
+                }],
+        };
+    });
+    server.registerTool("msg_send", {
+        title: "Send Message",
+        description: [
+            "Send a 1-to-1 message to another agent's inbox.",
+            "Messages are queued until consumed by msg_read (work queue pattern).",
+            "Use msg_whoami or msg_list_agents to discover available agents.",
+            "For announcements to ALL agents, use msg_broadcast instead.",
+        ].join(" "),
+        inputSchema: {
+            to: z.string().describe("Target agent name. Use msg_list_agents to see available agents."),
+            body: z.string().describe("Message body"),
+        },
+    }, async ({ to, body }) => {
+        const msg = {
+            id: crypto.randomUUID(),
+            from: identity.name,
+            to,
+            body,
+            timestamp: new Date().toISOString(),
+        };
+        await valkey.rpush(keys.inbox(to), JSON.stringify(msg));
+        await valkey.expire(keys.inbox(to), config.msgTtl);
+        await valkey.sadd(keys.agents(), to);
+        await valkey.sadd(keys.agents(), identity.name);
+        await valkey.publish(keys.notifyChannel(to), JSON.stringify(msg));
+        await publishEvent("msg_send", { from: identity.name, to, messageId: msg.id });
+        return {
+            content: [{ type: "text", text: `Message sent to "${to}" (id: ${msg.id})` }],
+        };
+    });
+    server.registerTool("msg_read", {
+        title: "Read Messages",
+        description: [
+            "Read and consume messages from your inbox (messages are removed after reading).",
+            "Use msg_check first to see if there are messages without consuming them.",
+            "Call this when msg_whoami or msg_check reports unread messages.",
+        ].join(" "),
+        inputSchema: {
+            inbox: z.string().optional().describe("Inbox to read. Defaults to this agent's own inbox."),
+            limit: z.number().optional().default(20).describe("Maximum messages to read"),
+        },
+    }, async ({ inbox, limit }) => {
+        const target = inbox ?? identity.name;
+        const maxMessages = limit ?? 20;
+        const raw = await valkey.lrange(keys.inbox(target), 0, maxMessages - 1);
+        if (raw.length === 0) {
+            return {
+                content: [{ type: "text", text: `No messages in inbox "${target}"` }],
+            };
+        }
+        const messages = raw.map((r) => JSON.parse(r));
+        // Always consume: remove the messages we just read
+        await valkey.ltrim(keys.inbox(target), raw.length, -1);
+        await publishEvent("msg_read", { inbox: target, count: raw.length });
+        await valkey.sadd(keys.agents(), target);
+        return {
+            content: [{
+                    type: "text",
+                    text: JSON.stringify(messages, null, 2),
+                }],
+        };
+    });
+    server.registerTool("msg_broadcast", {
+        title: "Broadcast Message",
+        description: [
+            "Broadcast a message to ALL agents.",
+            "Unlike msg_send, broadcasts are not consumed on read. Every agent sees them.",
+            "Broadcasts expire after the configured TTL (default 24h).",
+            "Use this for announcements: deploy freezes, CI status, completed migrations.",
+        ].join(" "),
+        inputSchema: {
+            body: z.string().describe("Broadcast message body"),
+        },
+    }, async ({ body }) => {
+        const bc = {
+            id: crypto.randomUUID(),
+            from: identity.name,
+            body,
+            timestamp: new Date().toISOString(),
+        };
+        await valkey.rpush(keys.broadcasts(), JSON.stringify(bc));
+        await valkey.expire(keys.broadcasts(), config.msgTtl);
+        await publishEvent("broadcast", { from: identity.name, messageId: bc.id });
+        return {
+            content: [{ type: "text", text: `Broadcast sent (id: ${bc.id})` }],
+        };
+    });
+    server.registerTool("msg_broadcasts", {
+        title: "Read Broadcasts",
+        description: [
+            "Read broadcast messages. Shows new broadcasts since your last check.",
+            "Broadcasts are shared across all agents and expire by TTL (not consumed on read).",
+            "Use all=true to see all broadcasts, not just unseen ones.",
+        ].join(" "),
+        inputSchema: {
+            all: z.boolean().optional().default(false).describe("Show all broadcasts, not just unseen"),
+        },
+    }, async ({ all: showAll }) => {
+        const raw = await valkey.lrange(keys.broadcasts(), 0, -1);
+        if (raw.length === 0) {
+            return {
+                content: [{ type: "text", text: "No broadcasts" }],
+            };
+        }
+        const broadcasts = raw.map((r) => JSON.parse(r));
+        if (showAll) {
+            await valkey.set(keys.broadcastCursor(identity.name), String(raw.length), "EX", config.msgTtl);
+            return {
+                content: [{
+                        type: "text",
+                        text: JSON.stringify({ total: broadcasts.length, broadcasts }, null, 2),
+                    }],
+            };
+        }
+        const cursorStr = await valkey.get(keys.broadcastCursor(identity.name));
+        const cursor = cursorStr ? parseInt(cursorStr, 10) : 0;
+        const unseen = broadcasts.slice(cursor);
+        // Update cursor
+        await valkey.set(keys.broadcastCursor(identity.name), String(raw.length), "EX", config.msgTtl);
+        if (unseen.length === 0) {
+            return {
+                content: [{
+                        type: "text",
+                        text: `No new broadcasts (${broadcasts.length} total, all seen)`,
+                    }],
+            };
+        }
+        return {
+            content: [{
+                    type: "text",
+                    text: JSON.stringify({ unseen: unseen.length, total: broadcasts.length, broadcasts: unseen }, null, 2),
+                }],
+        };
+    });
+}

package/dist/types.d.ts

@@ -0,0 +1,22 @@
+export interface Message {
+    id: string;
+    from: string;
+    to: string;
+    body: string;
+    timestamp: string;
+}
+export interface Broadcast {
+    id: string;
+    from: string;
+    body: string;
+    timestamp: string;
+}
+export interface Config {
+    valkeyUrl: string;
+    webPort: number;
+    webEnabled: boolean;
+    keyPrefix: string;
+    agentName: string;
+    msgTtl: number;
+}
+export declare function loadConfig(): Config;

package/dist/types.js

@@ -0,0 +1,20 @@
+function resolveAgentName() {
+    if (process.env.POSTINO_AGENT_NAME)
+        return process.env.POSTINO_AGENT_NAME;
+    const sessionId = process.env.TERM_SESSION_ID || process.env.ITERM_SESSION_ID;
+    if (sessionId) {
+        const short = sessionId.split(":").pop()?.slice(0, 8) ?? "";
+        return `agent-${short}`;
+    }
+    return `agent-${process.pid}`;
+}
+export function loadConfig() {
+    return {
+        valkeyUrl: process.env.POSTINO_VALKEY_URL ?? "redis://127.0.0.1:6379",
+        webPort: parseInt(process.env.POSTINO_WEB_PORT ?? "3333", 10),
+        webEnabled: process.env.POSTINO_WEB_ENABLED !== "false",
+        keyPrefix: process.env.POSTINO_KEY_PREFIX ?? "po:",
+        agentName: resolveAgentName(),
+        msgTtl: parseInt(process.env.POSTINO_MSG_TTL ?? "86400", 10),
+    };
+}

package/dist/valkey.d.ts

@@ -0,0 +1,19 @@
+import { Redis } from "ioredis";
+export declare const valkey: Redis;
+export declare const valkeySub: Redis;
+export declare const keys: {
+    inbox: (agent: string) => string;
+    agents: () => string;
+    agentInfo: (agent: string) => string;
+    broadcasts: () => string;
+    broadcastCursor: (agent: string) => string;
+    notifyChannel: (agent: string) => string;
+    eventsChannel: () => 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 renameAgent(oldName: string, newName: string): Promise<void>;
+export declare function getOnlineAgents(): Promise<string[]>;

package/dist/valkey.js

@@ -0,0 +1,109 @@
+import { Redis } from "ioredis";
+import { loadConfig } from "./types.js";
+const config = loadConfig();
+export const valkey = new Redis(config.valkeyUrl, {
+    lazyConnect: true,
+    maxRetriesPerRequest: 3,
+});
+export const valkeySub = new Redis(config.valkeyUrl, {
+    lazyConnect: true,
+    maxRetriesPerRequest: 3,
+});
+const prefix = config.keyPrefix;
+export const keys = {
+    inbox: (agent) => `${prefix}inbox:${agent}`,
+    agents: () => `${prefix}agents`,
+    agentInfo: (agent) => `${prefix}agent:${agent}`,
+    broadcasts: () => `${prefix}broadcasts`,
+    broadcastCursor: (agent) => `${prefix}bcursor:${agent}`,
+    notifyChannel: (agent) => `${prefix}notify:${agent}`,
+    eventsChannel: () => `${prefix}events`,
+};
+export async function connect() {
+    await valkey.connect();
+    await valkeySub.connect();
+}
+export async function disconnect() {
+    await valkey.quit();
+    await valkeySub.quit();
+}
+export async function publishEvent(type, data) {
+    const event = JSON.stringify({ type, ...data, timestamp: new Date().toISOString() });
+    await valkey.publish(keys.eventsChannel(), event);
+}
+const HEARTBEAT_TTL = 30;
+const HEARTBEAT_INTERVAL = 15_000;
+let heartbeatTimer = null;
+export async function registerAgent(name) {
+    const info = JSON.stringify({
+        name,
+        pid: process.pid,
+        started_at: new Date().toISOString(),
+    });
+    await valkey.set(keys.agentInfo(name), info, "EX", HEARTBEAT_TTL);
+    await valkey.sadd(keys.agents(), name);
+    await publishEvent("agent_online", { agent: name });
+    heartbeatTimer = setInterval(async () => {
+        try {
+            await valkey.expire(keys.agentInfo(name), HEARTBEAT_TTL);
+        }
+        catch {
+            // Connection lost
+        }
+    }, HEARTBEAT_INTERVAL);
+}
+export async function deregisterAgent(name) {
+    if (heartbeatTimer)
+        clearInterval(heartbeatTimer);
+    await valkey.del(keys.agentInfo(name));
+    await publishEvent("agent_offline", { agent: name });
+}
+export async function renameAgent(oldName, newName) {
+    // Stop heartbeat for old name
+    if (heartbeatTimer)
+        clearInterval(heartbeatTimer);
+    // Move inbox messages
+    const messages = await valkey.lrange(keys.inbox(oldName), 0, -1);
+    if (messages.length > 0) {
+        await valkey.rpush(keys.inbox(newName), ...messages);
+    }
+    await valkey.del(keys.inbox(oldName));
+    // Move broadcast cursor
+    const cursor = await valkey.get(keys.broadcastCursor(oldName));
+    if (cursor) {
+        const ttl = await valkey.ttl(keys.broadcastCursor(oldName));
+        await valkey.set(keys.broadcastCursor(newName), cursor, "EX", ttl > 0 ? ttl : HEARTBEAT_TTL);
+        await valkey.del(keys.broadcastCursor(oldName));
+    }
+    // Update agents set
+    await valkey.srem(keys.agents(), oldName);
+    await valkey.sadd(keys.agents(), newName);
+    // Deregister old, register new
+    await valkey.del(keys.agentInfo(oldName));
+    const info = JSON.stringify({
+        name: newName,
+        pid: process.pid,
+        started_at: new Date().toISOString(),
+    });
+    await valkey.set(keys.agentInfo(newName), info, "EX", HEARTBEAT_TTL);
+    // Restart heartbeat for new name
+    heartbeatTimer = setInterval(async () => {
+        try {
+            await valkey.expire(keys.agentInfo(newName), HEARTBEAT_TTL);
+        }
+        catch {
+            // Connection lost
+        }
+    }, HEARTBEAT_INTERVAL);
+    await publishEvent("agent_rename", { oldName, newName });
+}
+export async function getOnlineAgents() {
+    const allAgents = await valkey.smembers(keys.agents());
+    const online = [];
+    for (const name of allAgents) {
+        const exists = await valkey.exists(keys.agentInfo(name));
+        if (exists)
+            online.push(name);
+    }
+    return online.sort();
+}

package/dist/web/api.d.ts

@@ -0,0 +1,2 @@
+import { Hono } from "hono";
+export declare const api: Hono<import("hono/types").BlankEnv, import("hono/types").BlankSchema, "/">;

package/dist/web/api.js

@@ -0,0 +1,145 @@
+import { Hono } from "hono";
+import { streamSSE } from "hono/streaming";
+import { valkey, valkeySub, keys, publishEvent, getOnlineAgents } from "../valkey.js";
+import { loadConfig } from "../types.js";
+const config = loadConfig();
+export const api = new Hono();
+// --- Agents ---
+api.get("/agents", async (c) => {
+    const agents = await valkey.smembers(keys.agents());
+    agents.sort();
+    const onlineSet = new Set(await getOnlineAgents());
+    const result = [];
+    for (const agent of agents) {
+        const count = await valkey.llen(keys.inbox(agent));
+        result.push({ name: agent, messageCount: count, online: onlineSet.has(agent) });
+    }
+    return c.json(result);
+});
+// --- Messages ---
+api.get("/messages/:inbox", async (c) => {
+    const inbox = c.req.param("inbox");
+    const raw = await valkey.lrange(keys.inbox(inbox), 0, -1);
+    const messages = raw.map((r) => JSON.parse(r));
+    return c.json(messages);
+});
+api.post("/messages", async (c) => {
+    const body = await c.req.json();
+    const msg = {
+        id: crypto.randomUUID(),
+        from: body.from || "web-ui",
+        to: body.to,
+        body: body.body,
+        timestamp: new Date().toISOString(),
+    };
+    await valkey.rpush(keys.inbox(msg.to), JSON.stringify(msg));
+    await valkey.expire(keys.inbox(msg.to), config.msgTtl);
+    await valkey.sadd(keys.agents(), msg.to);
+    if (msg.from !== "anonymous") {
+        await valkey.sadd(keys.agents(), msg.from);
+    }
+    await valkey.publish(keys.notifyChannel(msg.to), JSON.stringify(msg));
+    await publishEvent("msg_send", { from: msg.from, to: msg.to, messageId: msg.id });
+    return c.json({ ok: true, id: msg.id });
+});
+api.delete("/messages/:inbox", async (c) => {
+    const inbox = c.req.param("inbox");
+    await valkey.del(keys.inbox(inbox));
+    await publishEvent("msg_read", { inbox, count: "all" });
+    return c.json({ ok: true });
+});
+// --- Broadcasts ---
+api.get("/broadcasts", async (c) => {
+    const all = await valkey.lrange(keys.broadcasts(), 0, -1);
+    const broadcasts = all.map((r) => JSON.parse(r));
+    return c.json(broadcasts);
+});
+api.post("/broadcasts", async (c) => {
+    const body = await c.req.json();
+    const bc = {
+        id: crypto.randomUUID(),
+        from: body.from || "web-ui",
+        body: body.body,
+        timestamp: new Date().toISOString(),
+    };
+    await valkey.rpush(keys.broadcasts(), JSON.stringify(bc));
+    await valkey.expire(keys.broadcasts(), config.msgTtl);
+    await publishEvent("broadcast", { from: bc.from, messageId: bc.id });
+    return c.json({ ok: true, id: bc.id });
+});
+api.delete("/broadcasts", async (c) => {
+    await valkey.del(keys.broadcasts());
+    await publishEvent("broadcasts_clear", {});
+    return c.json({ ok: true });
+});
+// --- Stats ---
+api.get("/stats", async (c) => {
+    const agents = await valkey.smembers(keys.agents());
+    let messageCount = 0;
+    for (const a of agents) {
+        messageCount += await valkey.llen(keys.inbox(a));
+    }
+    const broadcastCount = await valkey.llen(keys.broadcasts());
+    return c.json({ agentCount: agents.length, messageCount, broadcastCount });
+});
+// --- Agent-specific check (for hooks, zero-token) ---
+api.get("/check/:agent", async (c) => {
+    const agent = c.req.param("agent");
+    const unread = await valkey.llen(keys.inbox(agent));
+    const allBc = await valkey.lrange(keys.broadcasts(), 0, -1);
+    const cursorStr = await valkey.get(keys.broadcastCursor(agent));
+    const cursor = cursorStr ? parseInt(cursorStr, 10) : 0;
+    const unseenBc = Math.max(0, allBc.length - cursor);
+    return c.json({ agent, unreadMessages: unread, unseenBroadcasts: unseenBc });
+});
+const sseClients = new Set();
+let subscribedToEvents = false;
+function ensureEventSubscription() {
+    if (subscribedToEvents)
+        return;
+    subscribedToEvents = true;
+    valkeySub.subscribe(keys.eventsChannel()).catch(() => {
+        subscribedToEvents = false;
+    });
+    valkeySub.on("message", (_channel, message) => {
+        for (const client of sseClients) {
+            try {
+                client.send(message);
+            }
+            catch {
+                sseClients.delete(client);
+            }
+        }
+    });
+}
+api.get("/events", (c) => {
+    ensureEventSubscription();
+    return streamSSE(c, async (stream) => {
+        const clientId = crypto.randomUUID();
+        let alive = true;
+        const client = {
+            id: clientId,
+            send: (data) => {
+                if (alive) {
+                    stream.writeSSE({ data, event: "update" }).catch(() => {
+                        alive = false;
+                    });
+                }
+            },
+            close: () => {
+                alive = false;
+            },
+        };
+        sseClients.add(client);
+        await stream.writeSSE({ data: JSON.stringify({ type: "connected" }), event: "update" });
+        while (alive) {
+            await stream.sleep(15000);
+            if (alive) {
+                await stream.writeSSE({ data: "", event: "ping" }).catch(() => {
+                    alive = false;
+                });
+            }
+        }
+        sseClients.delete(client);
+    });
+});

package/dist/web/public/favicon.svg

@@ -0,0 +1,9 @@
+<svg width="32" height="32" viewBox="0 0 32 32" xmlns="http://www.w3.org/2000/svg">
+<rect width="32" height="32" rx="7" fill="#e63030"/>
+<g transform="translate(16,16)">
+  <rect x="-10" y="-4" width="20" height="8" rx="4" fill="none" stroke="white" stroke-width="1.5"/>
+  <line x1="-10" y1="-2" x2="-10" y2="2" stroke="white" stroke-width="1.5" stroke-linecap="round"/>
+  <rect x="-6" y="-2.5" width="6" height="4" rx="0.5" fill="white"/>
+  <rect x="1" y="-2.5" width="6" height="4" rx="0.5" fill="white" opacity="0.5"/>
+</g>
+</svg>