@rayhanadev/opencode-plugin-mailbox 0.0.1-beta.1 → 0.0.1-beta.3

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@rayhanadev/opencode-plugin-mailbox",
-  "version": "0.0.1-beta.1",
+  "version": "0.0.1-beta.3",
   "description": "Inter-agent communication plugin for OpenCode - enables real-time messaging between running agent sessions",
   "homepage": "https://github.com/rayhanadev/opencode-plugin-mailbox#readme",
   "bugs": {

package/src/hooks/messages.ts

@@ -0,0 +1,52 @@
+import type { PluginInput } from "@opencode-ai/plugin";
+
+import { getUnreadMessages } from "../inbox";
+import { isRegistered } from "../registry";
+
+type MessageInfo = {
+  sessionID: string;
+  role: string;
+};
+
+type MessageWithParts = {
+  info: MessageInfo;
+  parts: Array<{ type: string; text?: string }>;
+};
+
+function getSessionIdFromMessages(messages: MessageWithParts[]): string | null {
+  for (let i = messages.length - 1; i >= 0; i--) {
+    const msg = messages[i];
+    if (msg && msg.info.role === "user" && msg.info.sessionID) {
+      return msg.info.sessionID;
+    }
+  }
+  return null;
+}
+
+export function createMessagesTransformHook(_ctx: PluginInput) {
+  return async (
+    _input: {},
+    output: { messages: MessageWithParts[] },
+  ) => {
+    const sessionID = getSessionIdFromMessages(output.messages);
+    if (!sessionID) {
+      return;
+    }
+
+    if (!(await isRegistered(sessionID))) {
+      return;
+    }
+
+    const unreadMessages = await getUnreadMessages(sessionID);
+    if (unreadMessages.length === 0) {
+      return;
+    }
+
+    const notification = `You have ${unreadMessages.length} unread message(s) in your mailbox. Use mailbox_read to view them.`;
+
+    output.messages.push({
+      info: { sessionID, role: "user" },
+      parts: [{ type: "text", text: notification }],
+    });
+  };
+}

package/src/inbox.ts

@@ -0,0 +1,133 @@
+import { mkdir, readdir, unlink } from "node:fs/promises";
+import { homedir } from "node:os";
+import { join } from "node:path";
+
+import type { Message } from "./types";
+
+const INBOX_DIR = join(homedir(), ".opencode", "plugins", "mailbox", "inbox");
+
+function getSessionInboxDir(sessionId: string): string {
+  return join(INBOX_DIR, sessionId);
+}
+
+function getMessagePath(sessionId: string, messageId: string): string {
+  return join(getSessionInboxDir(sessionId), `${messageId}.json`);
+}
+
+export async function saveMessage(
+  input: Pick<Message, "from" | "to" | "content">,
+): Promise<Message> {
+  const message: Message = {
+    id: crypto.randomUUID(),
+    from: input.from,
+    to: input.to,
+    content: input.content,
+    timestamp: Date.now(),
+    read: false,
+  };
+
+  const inboxDir = getSessionInboxDir(message.to);
+  await mkdir(inboxDir, { recursive: true });
+
+  const messagePath = getMessagePath(message.to, message.id);
+  await Bun.write(messagePath, JSON.stringify(message, null, 2));
+
+  return message;
+}
+
+export async function getUnreadMessages(sessionId: string): Promise<Message[]> {
+  const inboxDir = getSessionInboxDir(sessionId);
+
+  try {
+    const files = await readdir(inboxDir);
+    const messages: Message[] = [];
+
+    for (const file of files) {
+      if (!file.endsWith(".json")) continue;
+
+      const filePath = join(inboxDir, file);
+      const content = await Bun.file(filePath).json();
+      const message = content as Message;
+
+      if (!message.read) {
+        messages.push(message);
+      }
+    }
+
+    return messages.sort((a, b) => a.timestamp - b.timestamp);
+  } catch {
+    return [];
+  }
+}
+
+export async function getAllMessages(sessionId: string): Promise<Message[]> {
+  const inboxDir = getSessionInboxDir(sessionId);
+
+  try {
+    const files = await readdir(inboxDir);
+    const messages: Message[] = [];
+
+    for (const file of files) {
+      if (!file.endsWith(".json")) continue;
+
+      const filePath = join(inboxDir, file);
+      const content = await Bun.file(filePath).json();
+      messages.push(content as Message);
+    }
+
+    return messages.sort((a, b) => a.timestamp - b.timestamp);
+  } catch {
+    return [];
+  }
+}
+
+export async function markAsRead(
+  sessionId: string,
+  messageId: string,
+): Promise<boolean> {
+  const messagePath = getMessagePath(sessionId, messageId);
+
+  try {
+    const file = Bun.file(messagePath);
+    if (!(await file.exists())) return false;
+
+    const message = (await file.json()) as Message;
+    message.read = true;
+    await Bun.write(messagePath, JSON.stringify(message, null, 2));
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+export async function markAllAsRead(sessionId: string): Promise<number> {
+  const messages = await getUnreadMessages(sessionId);
+  let count = 0;
+
+  for (const message of messages) {
+    if (await markAsRead(sessionId, message.id)) {
+      count++;
+    }
+  }
+
+  return count;
+}
+
+export async function deleteMessage(
+  sessionId: string,
+  messageId: string,
+): Promise<boolean> {
+  const messagePath = getMessagePath(sessionId, messageId);
+
+  try {
+    await unlink(messagePath);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+export async function getUnreadCount(sessionId: string): Promise<number> {
+  const messages = await getUnreadMessages(sessionId);
+  return messages.length;
+}

package/src/index.ts

@@ -1,8 +1,10 @@
 import type { Plugin } from "@opencode-ai/plugin";
 
 import { createEventHook } from "./hooks/events";
+import { createMessagesTransformHook } from "./hooks/messages";
 import { createCheckTool } from "./tools/check";
 import { createListTool } from "./tools/list";
+import { createReadTool } from "./tools/read";
 import { createRegisterTool } from "./tools/register";
 import { createReplyTool } from "./tools/reply";
 import { createSendTool } from "./tools/send";
@@ -12,11 +14,13 @@ export const MailboxPlugin: Plugin = async (ctx) => {
     tool: {
       mailbox_register: createRegisterTool(ctx),
       mailbox_list: createListTool(),
-      mailbox_send: createSendTool(ctx),
-      mailbox_reply: createReplyTool(ctx),
+      mailbox_send: createSendTool(),
+      mailbox_reply: createReplyTool(),
       mailbox_check: createCheckTool(),
+      mailbox_read: createReadTool(),
     },
     event: createEventHook(ctx),
+    "experimental.chat.messages.transform": createMessagesTransformHook(ctx),
   };
 };
 

package/src/tools/read.ts

@@ -0,0 +1,40 @@
+import { tool } from "@opencode-ai/plugin";
+
+import { getUnreadMessages, markAllAsRead } from "../inbox";
+import { isRegistered, getSession } from "../registry";
+
+export function createReadTool() {
+  return tool({
+    description:
+      "Read all unread messages from your mailbox inbox. Messages are automatically marked as read after viewing.",
+    args: {},
+    async execute(_args, toolCtx) {
+      if (!(await isRegistered(toolCtx.sessionID))) {
+        return "Error: You must register first. Use mailbox_register.";
+      }
+
+      const messages = await getUnreadMessages(toolCtx.sessionID);
+
+      if (messages.length === 0) {
+        return "No unread messages in your inbox.";
+      }
+
+      const formatted = await Promise.all(
+        messages.map(async (msg) => {
+          const senderInfo = await getSession(msg.from);
+          const senderLabel = senderInfo?.description
+            ? `${msg.from.slice(0, 12)}... (${senderInfo.description})`
+            : msg.from.slice(0, 12) + "...";
+
+          const timestamp = new Date(msg.timestamp).toLocaleString();
+
+          return `--- Message from ${senderLabel} at ${timestamp} ---\n${msg.content}`;
+        }),
+      );
+
+      await markAllAsRead(toolCtx.sessionID);
+
+      return `You have ${messages.length} message(s):\n\n${formatted.join("\n\n")}`;
+    },
+  });
+}

package/src/tools/reply.ts

@@ -1,11 +1,9 @@
-import type { PluginInput } from "@opencode-ai/plugin";
-
 import { tool } from "@opencode-ai/plugin";
 
-import { formatIncomingMessage } from "../format";
+import { saveMessage } from "../inbox";
 import { getLastSender, isRegistered, setLastSender } from "../registry";
 
-export function createReplyTool(ctx: PluginInput) {
+export function createReplyTool() {
   return tool({
     description:
       "Reply to the last agent session that messaged you. Convenience wrapper around mailbox_send.",
@@ -22,35 +20,20 @@ export function createReplyTool(ctx: PluginInput) {
         return "Error: No previous sender to reply to. Use mailbox_send instead.";
       }
 
-      const formattedMessage = formatIncomingMessage(
-        toolCtx.sessionID,
-        args.message,
-      );
-
       try {
-        await ctx.client.session.prompt({
-          path: { id: lastSender.sessionId },
-          body: {
-            parts: [{ type: "text", text: formattedMessage }],
-          },
+        await saveMessage({
+          from: toolCtx.sessionID,
+          to: lastSender.sessionId,
+          content: args.message,
         });
       } catch (error) {
         const msg = error instanceof Error ? error.message : String(error);
-        return `Error: Failed to deliver reply: ${msg}`;
+        return `Error: Failed to save reply: ${msg}`;
       }
 
       await setLastSender(lastSender.sessionId, toolCtx.sessionID);
 
-      try {
-        await ctx.client.tui.showToast({
-          body: {
-            message: `Reply sent to ${lastSender.sessionId.slice(0, 12)}...`,
-            variant: "success",
-          },
-        });
-      } catch {}
-
-      return `Reply sent to ${lastSender.sessionId}`;
+      return `Reply sent to ${lastSender.sessionId}. They will be notified on their next interaction.`;
     },
   });
 }

package/src/tools/send.ts

@@ -1,14 +1,12 @@
-import type { PluginInput } from "@opencode-ai/plugin";
-
 import { tool } from "@opencode-ai/plugin";
 
-import { formatIncomingMessage } from "../format";
+import { saveMessage } from "../inbox";
 import { resolveSessionId, isRegistered, setLastSender } from "../registry";
 
-export function createSendTool(ctx: PluginInput) {
+export function createSendTool() {
   return tool({
     description:
-      "Send a message to another registered agent session. The message is delivered in real-time to their chat. You must be registered (mailbox_register) before sending.",
+      "Send a message to another registered agent session. The message is delivered to their inbox and they will be notified on their next interaction. You must be registered (mailbox_register) before sending.",
     args: {
       to: tool.schema.string(
         "Session ID of the recipient (or unique prefix, min 6 chars)",
@@ -42,35 +40,20 @@ export function createSendTool(ctx: PluginInput) {
         return "Error: Cannot send a message to yourself.";
       }
 
-      const formattedMessage = formatIncomingMessage(
-        toolCtx.sessionID,
-        args.message,
-      );
-
       try {
-        await ctx.client.session.prompt({
-          path: { id: recipientId },
-          body: {
-            parts: [{ type: "text", text: formattedMessage }],
-          },
+        await saveMessage({
+          from: toolCtx.sessionID,
+          to: recipientId,
+          content: args.message,
         });
       } catch (error) {
         const msg = error instanceof Error ? error.message : String(error);
-        return `Error: Failed to deliver message: ${msg}`;
+        return `Error: Failed to save message: ${msg}`;
       }
 
       await setLastSender(recipientId, toolCtx.sessionID);
 
-      try {
-        await ctx.client.tui.showToast({
-          body: {
-            message: `Message sent to ${recipientId.slice(0, 12)}...`,
-            variant: "success",
-          },
-        });
-      } catch {}
-
-      return `Message sent to ${recipientId}`;
+      return `Message sent to ${recipientId}. They will be notified on their next interaction.`;
     },
   });
 }

package/src/types.ts

@@ -26,6 +26,7 @@ export interface Message {
   to: string;
   content: string;
   timestamp: number;
+  read: boolean;
 }
 
 export function createEmptyRegistry(): MailboxRegistry {