npm - @rayhanadev/opencode-plugin-mailbox - Versions diffs - 0.0.1-beta.1 - Mend

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

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (17) hide show

package/.oxfmtrc.json ADDED Viewed

@@ -0,0 +1,17 @@
+{
+  "$schema": "./node_modules/oxfmt/configuration_schema.json",
+  "printWidth": 80,
+  "tabWidth": 2,
+  "useTabs": false,
+  "semi": true,
+  "singleQuote": false,
+  "trailingComma": "all",
+  "arrowParens": "always",
+  "experimentalSortImports": {
+    "order": "asc",
+    "ignoreCase": true,
+    "newlinesBetween": true,
+    "internalPattern": ["@/**", "~/**"]
+  },
+  "ignorePatterns": ["**/node_modules/**", "**/dist/**", "**/*.min.js"]
+}

package/.oxlintrc.json ADDED Viewed

@@ -0,0 +1,14 @@
+{
+  "$schema": "./node_modules/oxlint/configuration_schema.json",
+  "plugins": ["typescript", "import"],
+  "env": {
+    "browser": true,
+    "node": true
+  },
+  "rules": {
+    "typescript/no-explicit-any": "error",
+    "typescript/consistent-type-imports": "error",
+    "import/no-cycle": "error"
+  },
+  "ignorePatterns": ["**/node_modules/**", "**/dist/**", "**/*.min.js"]
+}

package/AGENTS.md ADDED Viewed

@@ -0,0 +1,105 @@
+Default to using Bun instead of Node.js.
+- Use `bun <file>` instead of `node <file>` or `ts-node <file>`
+- Use `bun test` instead of `jest` or `vitest`
+- Use `bun build <file.html|file.ts|file.css>` instead of `webpack` or `esbuild`
+- Use `bun install` instead of `npm install` or `yarn install` or `pnpm install`
+- Use `bun run <script>` instead of `npm run <script>` or `yarn run <script>` or `pnpm run <script>`
+- Use `bunx <package> <command>` instead of `npx <package> <command>`
+- Bun automatically loads .env, so don't use dotenv.
+## APIs
+- `Bun.serve()` supports WebSockets, HTTPS, and routes. Don't use `express`.
+- `bun:sqlite` for SQLite. Don't use `better-sqlite3`.
+- `Bun.redis` for Redis. Don't use `ioredis`.
+- `Bun.sql` for Postgres. Don't use `pg` or `postgres.js`.
+- `WebSocket` is built-in. Don't use `ws`.
+- Prefer `Bun.file` over `node:fs`'s readFile/writeFile
+- Bun.$`ls` instead of execa.
+## Testing
+Use `bun test` to run tests.
+```ts#index.test.ts
+import { test, expect } from "bun:test";
+test("hello world", () => {
+  expect(1).toBe(1);
+});
+```
+## Frontend
+Use HTML imports with `Bun.serve()`. Don't use `vite`. HTML imports fully support React, CSS, Tailwind.
+Server:
+```ts#index.ts
+import index from "./index.html"
+Bun.serve({
+  routes: {
+    "/": index,
+    "/api/users/:id": {
+      GET: (req) => {
+        return new Response(JSON.stringify({ id: req.params.id }));
+      },
+    },
+  },
+  // optional websocket support
+  websocket: {
+    open: (ws) => {
+      ws.send("Hello, world!");
+    },
+    message: (ws, message) => {
+      ws.send(message);
+    },
+    close: (ws) => {
+      // handle close
+    }
+  },
+  development: {
+    hmr: true,
+    console: true,
+  }
+})
+```
+HTML files can import .tsx, .jsx or .js files directly and Bun's bundler will transpile & bundle automatically. `<link>` tags can point to stylesheets and Bun's CSS bundler will bundle.
+```html#index.html
+<html>
+  <body>
+    <h1>Hello, world!</h1>
+    <script type="module" src="./frontend.tsx"></script>
+  </body>
+</html>
+```
+With the following `frontend.tsx`:
+```tsx#frontend.tsx
+import React from "react";
+import { createRoot } from "react-dom/client";
+// import .css files directly and it works
+import './index.css';
+const root = createRoot(document.body);
+export default function Frontend() {
+  return <h1>Hello, world!</h1>;
+}
+root.render(<Frontend />);
+```
+Then, run index.ts
+```sh
+bun --hot ./index.ts
+```
+For more information, read the Bun API docs in `node_modules/bun-types/docs/**.mdx`.

package/LICENSE ADDED Viewed

@@ -0,0 +1,21 @@
+MIT License
+Copyright (c) 2025 Rayhan Noufal Arayilakath
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md ADDED Viewed

@@ -0,0 +1,113 @@
+# opencode-plugin-mailbox
+Inter-agent communication plugin for [OpenCode](https://github.com/opencode-ai/opencode). Enables real-time messaging between running agent sessions.
+## Installation
+```bash
+bun install
+```
+Add to your OpenCode config (`~/.config/opencode/config.json`):
+```json
+{
+  "plugins": [
+    "@rayhanadev/opencode-plugin-mailbox"
+  ]
+}
+```
+## Tools
+### `mailbox_register`
+Register your session to enable messaging. Required before sending or receiving.
+```
+mailbox_register description="Working on API integration"
+```
+### `mailbox_list`
+List all registered sessions available for communication.
+```
+mailbox_list
+```
+Output:
+```
+| Session ID   | Directory        | Description              | Last Seen |
+| ------------ | ---------------- | ------------------------ | --------- |
+| ses_a1b2c3d4 | /path/to/project | Working on API integration | just now  |
+| ses_x7y8z9w0 | /path/to/project | (you)                    | -         |
+```
+### `mailbox_send`
+Send a message to another session. Delivered in real-time.
+```
+mailbox_send to="ses_a1b" message="Found the authentication docs you needed"
+```
+Session IDs support partial matching (minimum 6 characters).
+### `mailbox_reply`
+Reply to the last session that messaged you.
+```
+mailbox_reply message="Thanks, implementing now!"
+```
+### `mailbox_check`
+Check your registration status and who last messaged you.
+```
+mailbox_check
+```
+## How It Works
+1. Each session registers with `mailbox_register`
+2. Sessions discover each other via `mailbox_list`
+3. Messages are delivered in real-time using OpenCode's `session.prompt()` API
+4. Recipients see messages injected directly into their chat
+5. Sessions are automatically cleaned up when they end
+## Message Format
+When you receive a message, it appears as:
+```
+📬 MAILBOX
+From: ses_a1b2c3d4 | 2:34:15 PM
+────────────────────────────────
+Here's the API documentation you requested...
+────────────────────────────────
+Use mailbox_reply to respond
+```
+## Registry
+Session data is stored at `~/.opencode/plugins/mailbox/registry.json`. This enables:
+- Discovery across all OpenCode projects (global scope)
+- Persistence across plugin restarts
+- Reply context tracking
+## Development
+```bash
+bun run typecheck
+```
+## License
+MIT

package/package.json ADDED Viewed

@@ -0,0 +1,39 @@
+{
+  "name": "@rayhanadev/opencode-plugin-mailbox",
+  "version": "0.0.1-beta.1",
+  "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": {
+    "url": "https://github.com/rayhanadev/opencode-plugin-mailbox/issues"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/rayhanadev/opencode-plugin-mailbox.git"
+  },
+  "license": "MIT",
+  "author": "Rayhan Noufal Arayilakath <me@rayhanadev.com>",
+  "type": "module",
+  "main": "src/index.ts",
+  "scripts": {
+    "lint": "oxlint --type-aware",
+    "format": "oxfmt",
+    "typecheck": "tsc --noEmit",
+    "build": "bun build src/index.ts --outdir dist --target node"
+  },
+  "dependencies": {
+    "@opencode-ai/plugin": "^1.0.221"
+  },
+  "devDependencies": {
+    "@types/bun": "latest",
+    "oxfmt": "^0.21.0",
+    "oxlint": "^1.36.0",
+    "oxlint-tsgolint": "^0.10.0"
+  },
+  "peerDependencies": {
+    "typescript": "^5"
+  },
+  "publishConfig": {
+    "registry": "https://registry.npmjs.org/",
+    "access": "public"
+  }
+}

package/src/format.ts ADDED Viewed

@@ -0,0 +1,59 @@
+export function formatIncomingMessage(
+  fromSessionId: string,
+  content: string,
+): string {
+  const time = new Date().toLocaleTimeString();
+  return `📬 **MAILBOX**
+From: ${fromSessionId} | ${time}
+────────────────────────────────
+${content}
+────────────────────────────────
+Use mailbox_reply to respond`;
+}
+export function formatSessionTable(
+  sessions: Array<{
+    sessionId: string;
+    projectID: string;
+    directory: string;
+    description?: string;
+    lastSeen: number;
+  }>,
+  currentSessionId: string,
+): string {
+  if (sessions.length === 0) {
+    return "No registered sessions. Use mailbox_register to register.";
+  }
+  const header = "| Session ID | Project | Directory | Description | Status |";
+  const separator =
+    "| ---------- | ------- | --------- | ----------- | ------ |";
+  const rows = sessions.map((s) => {
+    const isYou = s.sessionId === currentSessionId;
+    const truncatedId = s.sessionId.slice(0, 12) + "...";
+    const truncatedProject = truncate(s.projectID, 15);
+    const truncatedDir = truncate(s.directory.split("/").pop() || "", 15);
+    const description = s.description || "-";
+    const status = isYou ? "(you)" : formatLastSeen(s.lastSeen);
+    return `| ${truncatedId} | ${truncatedProject} | ${truncatedDir} | ${description} | ${status} |`;
+  });
+  return [header, separator, ...rows].join("\n");
+}
+function truncate(str: string, maxLen: number): string {
+  if (str.length <= maxLen) return str;
+  return str.slice(0, maxLen - 3) + "...";
+}
+function formatLastSeen(timestamp: number): string {
+  const seconds = Math.floor((Date.now() - timestamp) / 1000);
+  if (seconds < 60) return "active";
+  if (seconds < 3600) return `${Math.floor(seconds / 60)}m ago`;
+  if (seconds < 86400) return `${Math.floor(seconds / 3600)}h ago`;
+  return `${Math.floor(seconds / 86400)}d ago`;
+}

package/src/hooks/events.ts ADDED Viewed

@@ -0,0 +1,19 @@
+import type { PluginInput } from "@opencode-ai/plugin";
+import { unregisterSession, updateLastSeen } from "../registry";
+export function createEventHook(_ctx: PluginInput) {
+  return async ({
+    event,
+  }: {
+    event: { type: string; properties?: Record<string, unknown> };
+  }) => {
+    if (event.type === "session.deleted" && event.properties?.sessionID) {
+      await unregisterSession(event.properties.sessionID as string);
+    }
+    if (event.type === "session.idle" && event.properties?.sessionID) {
+      await updateLastSeen(event.properties.sessionID as string);
+    }
+  };
+}

package/src/index.ts ADDED Viewed

@@ -0,0 +1,23 @@
+import type { Plugin } from "@opencode-ai/plugin";
+import { createEventHook } from "./hooks/events";
+import { createCheckTool } from "./tools/check";
+import { createListTool } from "./tools/list";
+import { createRegisterTool } from "./tools/register";
+import { createReplyTool } from "./tools/reply";
+import { createSendTool } from "./tools/send";
+export const MailboxPlugin: Plugin = async (ctx) => {
+  return {
+    tool: {
+      mailbox_register: createRegisterTool(ctx),
+      mailbox_list: createListTool(),
+      mailbox_send: createSendTool(ctx),
+      mailbox_reply: createReplyTool(ctx),
+      mailbox_check: createCheckTool(),
+    },
+    event: createEventHook(ctx),
+  };
+};
+export default MailboxPlugin;

package/src/registry.ts ADDED Viewed

@@ -0,0 +1,205 @@
+import { mkdir } from "node:fs/promises";
+import { homedir } from "node:os";
+import { join } from "node:path";
+import {
+  type MailboxRegistry,
+  type SessionEntry,
+  createEmptyRegistry,
+} from "./types";
+const REGISTRY_DIR = join(homedir(), ".opencode", "plugins", "mailbox");
+const REGISTRY_PATH = join(REGISTRY_DIR, "registry.json");
+const LOCK_PATH = join(REGISTRY_DIR, "registry.lock");
+async function ensureDir(): Promise<void> {
+  await mkdir(REGISTRY_DIR, { recursive: true });
+}
+async function acquireLock(timeout = 5000): Promise<void> {
+  const start = Date.now();
+  const lockFile = Bun.file(LOCK_PATH);
+  while (Date.now() - start < timeout) {
+    try {
+      const exists = await lockFile.exists();
+      if (!exists) {
+        await Bun.write(LOCK_PATH, String(process.pid));
+        return;
+      }
+      const stat = await lockFile.stat();
+      const isStale = stat && Date.now() - stat.mtime.getTime() > 30000;
+      if (isStale) {
+        await Bun.write(LOCK_PATH, String(process.pid));
+        return;
+      }
+      await Bun.sleep(50);
+    } catch {
+      await Bun.sleep(50);
+    }
+  }
+  throw new Error("Failed to acquire registry lock - timeout");
+}
+async function releaseLock(): Promise<void> {
+  try {
+    const { unlink } = await import("node:fs/promises");
+    await unlink(LOCK_PATH);
+  } catch {}
+}
+async function readRegistry(): Promise<MailboxRegistry> {
+  try {
+    const file = Bun.file(REGISTRY_PATH);
+    if (await file.exists()) {
+      return await file.json();
+    }
+  } catch {}
+  return createEmptyRegistry();
+}
+async function writeRegistry(registry: MailboxRegistry): Promise<void> {
+  await Bun.write(REGISTRY_PATH, JSON.stringify(registry, null, 2));
+}
+export async function withRegistry<T>(
+  fn: (registry: MailboxRegistry) => T | Promise<T>,
+  options: { write?: boolean } = {},
+): Promise<T> {
+  await ensureDir();
+  await acquireLock();
+  try {
+    const registry = await readRegistry();
+    const result = await fn(registry);
+    if (options.write) {
+      await writeRegistry(registry);
+    }
+    return result;
+  } finally {
+    await releaseLock();
+  }
+}
+export async function registerSession(
+  sessionId: string,
+  entry: Omit<SessionEntry, "registeredAt" | "lastSeen">,
+): Promise<void> {
+  await withRegistry(
+    (registry) => {
+      registry.sessions[sessionId] = {
+        ...entry,
+        registeredAt: Date.now(),
+        lastSeen: Date.now(),
+      };
+    },
+    { write: true },
+  );
+}
+export async function unregisterSession(sessionId: string): Promise<void> {
+  await withRegistry(
+    (registry) => {
+      delete registry.sessions[sessionId];
+      delete registry.lastSender[sessionId];
+      for (const [recipientId, sender] of Object.entries(registry.lastSender)) {
+        if (sender.sessionId === sessionId) {
+          delete registry.lastSender[recipientId];
+        }
+      }
+    },
+    { write: true },
+  );
+}
+export async function updateLastSeen(sessionId: string): Promise<void> {
+  await withRegistry(
+    (registry) => {
+      if (registry.sessions[sessionId]) {
+        registry.sessions[sessionId].lastSeen = Date.now();
+      }
+    },
+    { write: true },
+  );
+}
+export async function setLastSender(
+  recipientSessionId: string,
+  senderSessionId: string,
+): Promise<void> {
+  await withRegistry(
+    (registry) => {
+      registry.lastSender[recipientSessionId] = {
+        sessionId: senderSessionId,
+        timestamp: Date.now(),
+      };
+    },
+    { write: true },
+  );
+}
+export async function getLastSender(
+  recipientSessionId: string,
+): Promise<{ sessionId: string; timestamp: number } | null> {
+  return await withRegistry((registry) => {
+    return registry.lastSender[recipientSessionId] || null;
+  });
+}
+export async function getSession(
+  sessionId: string,
+): Promise<SessionEntry | null> {
+  return await withRegistry((registry) => {
+    return registry.sessions[sessionId] || null;
+  });
+}
+export async function getAllSessions(): Promise<
+  Array<{ sessionId: string } & SessionEntry>
+> {
+  return await withRegistry((registry) => {
+    return Object.entries(registry.sessions).map(([sessionId, entry]) => ({
+      sessionId,
+      ...entry,
+    }));
+  });
+}
+export async function isRegistered(sessionId: string): Promise<boolean> {
+  return await withRegistry((registry) => {
+    return sessionId in registry.sessions;
+  });
+}
+export async function resolveSessionId(
+  partialId: string,
+): Promise<{ sessionId: string; entry: SessionEntry } | null> {
+  return await withRegistry((registry) => {
+    if (registry.sessions[partialId]) {
+      return { sessionId: partialId, entry: registry.sessions[partialId] };
+    }
+    const matches = Object.entries(registry.sessions).filter(([id]) =>
+      id.startsWith(partialId),
+    );
+    if (matches.length === 1) {
+      const match = matches[0]!;
+      return { sessionId: match[0], entry: match[1] };
+    }
+    if (matches.length > 1) {
+      throw new Error(
+        `Ambiguous session ID "${partialId}" - matches: ${matches.map(([id]) => id).join(", ")}`,
+      );
+    }
+    return null;
+  });
+}

package/src/tools/check.ts ADDED Viewed

@@ -0,0 +1,46 @@
+import { tool } from "@opencode-ai/plugin";
+import { isRegistered, getSession, getLastSender } from "../registry";
+export function createCheckTool() {
+  return tool({
+    description:
+      "Check your mailbox registration status and who last messaged you.",
+    args: {},
+    async execute(_args, toolCtx) {
+      const registered = await isRegistered(toolCtx.sessionID);
+      if (!registered) {
+        return `Status: Not registered\nYour ID: ${toolCtx.sessionID}\n\nUse mailbox_register to register.`;
+      }
+      const session = await getSession(toolCtx.sessionID);
+      const lastSender = await getLastSender(toolCtx.sessionID);
+      let result = `Status: Registered\nYour ID: ${toolCtx.sessionID}`;
+      if (session?.description) {
+        result += `\nDescription: ${session.description}`;
+      }
+      if (lastSender) {
+        const ago = formatTimeAgo(lastSender.timestamp);
+        result += `\n\nLast message from: ${lastSender.sessionId} (${ago})`;
+        result += `\nUse mailbox_reply to respond.`;
+      } else {
+        result += `\n\nNo messages received yet.`;
+      }
+      return result;
+    },
+  });
+}
+function formatTimeAgo(timestamp: number): string {
+  const seconds = Math.floor((Date.now() - timestamp) / 1000);
+  if (seconds < 60) return "just now";
+  if (seconds < 3600) return `${Math.floor(seconds / 60)} min ago`;
+  if (seconds < 86400) return `${Math.floor(seconds / 3600)} hours ago`;
+  return `${Math.floor(seconds / 86400)} days ago`;
+}

package/src/tools/list.ts ADDED Viewed

@@ -0,0 +1,21 @@
+import { tool } from "@opencode-ai/plugin";
+import { formatSessionTable } from "../format";
+import { getAllSessions } from "../registry";
+export function createListTool() {
+  return tool({
+    description:
+      "List all registered agent sessions available for mailbox communication.",
+    args: {},
+    async execute(_args, toolCtx) {
+      const sessions = await getAllSessions();
+      if (sessions.length === 0) {
+        return "No sessions registered. Use mailbox_register to register this session.";
+      }
+      return formatSessionTable(sessions, toolCtx.sessionID);
+    },
+  });
+}

package/src/tools/register.ts ADDED Viewed

@@ -0,0 +1,36 @@
+import type { PluginInput } from "@opencode-ai/plugin";
+import { tool } from "@opencode-ai/plugin";
+import { registerSession, isRegistered } from "../registry";
+export function createRegisterTool(ctx: PluginInput) {
+  return tool({
+    description:
+      "Register this session for mailbox communication. Required before sending or receiving messages from other agents.",
+    args: {
+      description: tool.schema
+        .string("Optional description of what this agent is working on")
+        .optional(),
+    },
+    async execute(args, toolCtx) {
+      if (await isRegistered(toolCtx.sessionID)) {
+        return `Already registered: ${toolCtx.sessionID}`;
+      }
+      await registerSession(toolCtx.sessionID, {
+        projectID: ctx.project.id,
+        directory: ctx.directory,
+        description: args.description,
+      });
+      try {
+        await ctx.client.tui.showToast({
+          body: { message: `Mailbox: Registered`, variant: "success" },
+        });
+      } catch {}
+      return `Registered: ${toolCtx.sessionID}\nOther agents can now send you messages.`;
+    },
+  });
+}

package/src/tools/reply.ts ADDED Viewed

@@ -0,0 +1,56 @@
+import type { PluginInput } from "@opencode-ai/plugin";
+import { tool } from "@opencode-ai/plugin";
+import { formatIncomingMessage } from "../format";
+import { getLastSender, isRegistered, setLastSender } from "../registry";
+export function createReplyTool(ctx: PluginInput) {
+  return tool({
+    description:
+      "Reply to the last agent session that messaged you. Convenience wrapper around mailbox_send.",
+    args: {
+      message: tool.schema.string("Your reply message"),
+    },
+    async execute(args, toolCtx) {
+      if (!(await isRegistered(toolCtx.sessionID))) {
+        return "Error: You must register first. Use mailbox_register.";
+      }
+      const lastSender = await getLastSender(toolCtx.sessionID);
+      if (!lastSender) {
+        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 }],
+          },
+        });
+      } catch (error) {
+        const msg = error instanceof Error ? error.message : String(error);
+        return `Error: Failed to deliver 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}`;
+    },
+  });
+}

package/src/tools/send.ts ADDED Viewed

@@ -0,0 +1,76 @@
+import type { PluginInput } from "@opencode-ai/plugin";
+import { tool } from "@opencode-ai/plugin";
+import { formatIncomingMessage } from "../format";
+import { resolveSessionId, isRegistered, setLastSender } from "../registry";
+export function createSendTool(ctx: PluginInput) {
+  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.",
+    args: {
+      to: tool.schema.string(
+        "Session ID of the recipient (or unique prefix, min 6 chars)",
+      ),
+      message: tool.schema.string("The message content to send"),
+    },
+    async execute(args, toolCtx) {
+      if (!(await isRegistered(toolCtx.sessionID))) {
+        return "Error: You must register first. Use mailbox_register.";
+      }
+      if (args.to.length < 6) {
+        return "Error: Session ID prefix must be at least 6 characters.";
+      }
+      let resolved: { sessionId: string } | null;
+      try {
+        resolved = await resolveSessionId(args.to);
+      } catch (error) {
+        const msg = error instanceof Error ? error.message : String(error);
+        return `Error: ${msg}`;
+      }
+      if (!resolved) {
+        return `Error: No session found matching "${args.to}". Use mailbox_list to see available sessions.`;
+      }
+      const recipientId = resolved.sessionId;
+      if (recipientId === toolCtx.sessionID) {
+        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 }],
+          },
+        });
+      } catch (error) {
+        const msg = error instanceof Error ? error.message : String(error);
+        return `Error: Failed to deliver 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}`;
+    },
+  });
+}

package/src/types.ts ADDED Viewed

@@ -0,0 +1,36 @@
+export interface SessionEntry {
+  projectID: string;
+  directory: string;
+  description?: string;
+  registeredAt: number;
+  lastSeen: number;
+}
+export interface LastSender {
+  sessionId: string;
+  timestamp: number;
+}
+export interface MailboxRegistry {
+  sessions: {
+    [sessionId: string]: SessionEntry;
+  };
+  lastSender: {
+    [recipientSessionId: string]: LastSender;
+  };
+}
+export interface Message {
+  id: string;
+  from: string;
+  to: string;
+  content: string;
+  timestamp: number;
+}
+export function createEmptyRegistry(): MailboxRegistry {
+  return {
+    sessions: {},
+    lastSender: {},
+  };
+}

package/tsconfig.json ADDED Viewed

@@ -0,0 +1,29 @@
+{
+  "compilerOptions": {
+    // Environment setup & latest features
+    "lib": ["ESNext"],
+    "target": "ESNext",
+    "module": "Preserve",
+    "moduleDetection": "force",
+    "jsx": "react-jsx",
+    "allowJs": true,
+    // Bundler mode
+    "moduleResolution": "bundler",
+    "allowImportingTsExtensions": true,
+    "verbatimModuleSyntax": true,
+    "noEmit": true,
+    // Best practices
+    "strict": true,
+    "skipLibCheck": true,
+    "noFallthroughCasesInSwitch": true,
+    "noUncheckedIndexedAccess": true,
+    "noImplicitOverride": true,
+    // Some stricter flags (disabled by default)
+    "noUnusedLocals": false,
+    "noUnusedParameters": false,
+    "noPropertyAccessFromIndexSignature": false
+  }
+}