@spoons-and-mirrors/iam 0.1.0

package/README.md

@@ -0,0 +1,40 @@
+# IAM Plugin for OpenCode
+
+Inter-agent messaging for parallel subagents.
+
+## The `iam` Tool
+
+| Action | Args | Description |
+|--------|------|-------------|
+| `sessions` | - | List agents you can message |
+| `read` | - | Read your messages (marks as read) |
+| `write` | `--to <id> --message "..."` | Send a message |
+
+## Examples
+
+```bash
+iam sessions
+iam read
+iam write --to ses_abc123 --message "What approach are you using?"
+```
+
+## How It Works
+
+- **In-memory** - fast, no file clutter, resets on restart
+- **Auto-discovery** - agents register on first iam use, see each other immediately
+- **Urgent alerts** - recipients get `<system-reminder>` when they have unread mail
+
+## Files
+
+```
+iam/
+├── index.ts      # Plugin + tool + hooks
+├── prompt.ts     # LLM-facing prompts
+├── logger.ts     # Logs to .logs/iam.log
+├── PROGRESS.md   # Development history
+└── README.md
+```
+
+## Logs
+
+Debug logs written to `.logs/iam.log` (clears on restart). Shows all tool calls, messages sent, sessions registered, and notifications injected.

package/dist/index.d.ts

@@ -0,0 +1,4 @@
+import type { Plugin } from "@opencode-ai/plugin";
+declare const plugin: Plugin;
+export default plugin;
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../index.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,qBAAqB,CAAA;AA0GjD,QAAA,MAAM,MAAM,EAAE,MAwIb,CAAA;AAED,eAAe,MAAM,CAAA"}

package/dist/index.js

@@ -0,0 +1,274 @@
+// index.ts
+import { tool } from "@opencode-ai/plugin";
+
+// prompt.ts
+var TOOL_DESCRIPTION = `Inter-agent messaging. Use this to communicate with other parallel agents (task tools).
+
+Actions:
+- "sessions": Show session IDs of agents you can message
+- "read": Read all your messages (marks them as read)
+- "write": Send a message to another agent`;
+var ARG_DESCRIPTIONS = {
+  action: "Action to perform",
+  to: "Recipient session ID (required for 'write')",
+  message: "Message content (required for 'write')"
+};
+var SESSIONS_EMPTY = `No other agents available yet.
+
+Agents will appear here when:
+- Parallel tasks are spawned by the same parent
+- Another agent sends you a message`;
+function sessionsResult(agents) {
+  return [
+    `Agents you can message:
+`,
+    ...agents.map((id) => `- ${id}`),
+    ``,
+    `Use: iam write --to <session_id> --message "..."`
+  ].join(`
+`);
+}
+var READ_EMPTY = `No messages in your iam.`;
+function readResult(messages, unreadCount) {
+  const lines = [`Your iam (${unreadCount} were unread):
+`, `---`];
+  for (const msg of messages) {
+    const time = new Date(msg.timestamp).toISOString();
+    const status = msg.read ? "" : " [NEW]";
+    lines.push(`[${time}] From: ${msg.from}${status}`);
+    lines.push(msg.body);
+    lines.push(`---`);
+  }
+  lines.push(``);
+  lines.push(`To reply: iam write --to <sender_session_id> --message "..."`);
+  return lines.join(`
+`);
+}
+var WRITE_MISSING_TO = `Error: 'to' is required. Use: iam write --to <session_id> --message "..."`;
+var WRITE_MISSING_MESSAGE = `Error: 'message' is required. Use: iam write --to <session_id> --message "..."`;
+function writeResult(to, messageId) {
+  return `Message sent!
+
+To: ${to}
+Message ID: ${messageId}
+
+The recipient will be notified.`;
+}
+function unknownAction(action) {
+  return `Unknown action: ${action}`;
+}
+var SYSTEM_PROMPT = `
+# Inter-Agent Messaging
+
+You have access to an \`iam\` tool for communicating with other parallel agents.
+
+Commands:
+- \`iam sessions\` - See agents you can message
+- \`iam read\` - Read all your messages
+- \`iam write --to <session_id> --message "..."\` - Send a message
+
+Check your iam when notified about new messages.
+`;
+function urgentNotification(unreadCount) {
+  return `<system-reminder priority="critical">
+URGENT: You have ${unreadCount} unread message(s) in your iam.
+Use \`iam read\` NOW to check your messages before continuing other work.
+</system-reminder>`;
+}
+
+// logger.ts
+import * as fs from "fs";
+import * as path from "path";
+var LOG_DIR = path.join(process.cwd(), ".logs");
+var LOG_FILE = path.join(LOG_DIR, "iam.log");
+try {
+  if (!fs.existsSync(LOG_DIR)) {
+    fs.mkdirSync(LOG_DIR, { recursive: true });
+  }
+  fs.writeFileSync(LOG_FILE, "");
+} catch {}
+function formatTimestamp() {
+  return new Date().toISOString();
+}
+function writeLog(level, category, message, data) {
+  const timestamp = formatTimestamp();
+  const dataStr = data !== undefined ? ` | ${JSON.stringify(data)}` : "";
+  const logLine = `[${timestamp}] [${level}] [${category}] ${message}${dataStr}
+`;
+  try {
+    fs.appendFileSync(LOG_FILE, logLine);
+  } catch {}
+}
+var log = {
+  debug: (category, message, data) => writeLog("DEBUG", category, message, data),
+  info: (category, message, data) => writeLog("INFO", category, message, data),
+  warn: (category, message, data) => writeLog("WARN", category, message, data),
+  error: (category, message, data) => writeLog("ERROR", category, message, data)
+};
+var LOG = {
+  TOOL: "TOOL",
+  MESSAGE: "MESSAGE",
+  SESSION: "SESSION",
+  HOOK: "HOOK",
+  INJECT: "INJECT"
+};
+
+// index.ts
+var inboxes = new Map;
+var activeSessions = new Set;
+function generateId() {
+  return Math.random().toString(36).substring(2, 10);
+}
+function getInbox(sessionId) {
+  if (!inboxes.has(sessionId)) {
+    inboxes.set(sessionId, []);
+  }
+  return inboxes.get(sessionId);
+}
+function sendMessage(from, to, body) {
+  const message = {
+    id: generateId(),
+    from,
+    to,
+    body,
+    timestamp: Date.now(),
+    read: false
+  };
+  getInbox(to).push(message);
+  log.info(LOG.MESSAGE, `Message sent`, { id: message.id, from, to, bodyLength: body.length });
+  return message;
+}
+function getUnreadMessages(sessionId) {
+  return getInbox(sessionId).filter((m) => !m.read);
+}
+function getAllMessages(sessionId) {
+  return getInbox(sessionId);
+}
+function markAllRead(sessionId) {
+  const iam = getInbox(sessionId);
+  const unreadCount = iam.filter((m) => !m.read).length;
+  for (const msg of iam) {
+    msg.read = true;
+  }
+  log.info(LOG.MESSAGE, `Marked all read`, { sessionId, count: unreadCount });
+}
+function getKnownAgents(sessionId) {
+  const agents = [];
+  for (const id of activeSessions) {
+    if (id !== sessionId) {
+      agents.push(id);
+    }
+  }
+  return agents;
+}
+function registerSession(sessionId) {
+  if (!activeSessions.has(sessionId)) {
+    activeSessions.add(sessionId);
+    log.info(LOG.SESSION, `Session registered`, { sessionId, totalSessions: activeSessions.size });
+  }
+}
+var plugin = async () => {
+  log.info(LOG.HOOK, "Plugin initialized");
+  return {
+    tool: {
+      iam: tool({
+        description: TOOL_DESCRIPTION,
+        args: {
+          action: tool.schema.enum(["sessions", "read", "write"]).describe(ARG_DESCRIPTIONS.action),
+          to: tool.schema.string().optional().describe(ARG_DESCRIPTIONS.to),
+          message: tool.schema.string().optional().describe(ARG_DESCRIPTIONS.message)
+        },
+        async execute(args, context) {
+          const sessionId = context.sessionID;
+          registerSession(sessionId);
+          log.debug(LOG.TOOL, `iam action: ${args.action}`, { sessionId, args });
+          switch (args.action) {
+            case "sessions": {
+              const agents = getKnownAgents(sessionId);
+              log.debug(LOG.TOOL, `sessions result`, { sessionId, agentCount: agents.length, agents });
+              if (agents.length === 0) {
+                return SESSIONS_EMPTY;
+              }
+              return sessionsResult(agents);
+            }
+            case "read": {
+              const messages = getAllMessages(sessionId);
+              const unreadCount = messages.filter((m) => !m.read).length;
+              log.debug(LOG.TOOL, `read iam`, { sessionId, total: messages.length, unread: unreadCount });
+              markAllRead(sessionId);
+              if (messages.length === 0) {
+                return READ_EMPTY;
+              }
+              return readResult(messages, unreadCount);
+            }
+            case "write": {
+              if (!args.to) {
+                log.warn(LOG.TOOL, `write missing 'to'`, { sessionId });
+                return WRITE_MISSING_TO;
+              }
+              if (!args.message) {
+                log.warn(LOG.TOOL, `write missing 'message'`, { sessionId });
+                return WRITE_MISSING_MESSAGE;
+              }
+              const msg = sendMessage(sessionId, args.to, args.message);
+              return writeResult(args.to, msg.id);
+            }
+            default:
+              return unknownAction(args.action);
+          }
+        }
+      })
+    },
+    "tool.execute.after": async (input, output) => {
+      log.debug(LOG.HOOK, `tool.execute.after fired`, { tool: input.tool, sessionID: input.sessionID, hasMetadata: !!output.metadata });
+      if (input.tool === "task") {
+        log.debug(LOG.HOOK, `task metadata`, { metadata: output.metadata, output: output.output?.substring?.(0, 200) });
+        const newSessionId = output.metadata?.sessionId || output.metadata?.session_id;
+        if (newSessionId) {
+          log.info(LOG.HOOK, `task completed, registering session`, { newSessionId });
+          registerSession(newSessionId);
+        } else {
+          log.warn(LOG.HOOK, `task completed but no session_id in metadata`);
+        }
+      }
+    },
+    "experimental.chat.system.transform": async (_input, output) => {
+      output.system.push(SYSTEM_PROMPT);
+    },
+    "experimental.chat.messages.transform": async (_input, output) => {
+      const lastUserMsg = [...output.messages].reverse().find((m) => m.info.role === "user");
+      if (!lastUserMsg)
+        return;
+      const sessionId = lastUserMsg.info.sessionID;
+      const unread = getUnreadMessages(sessionId);
+      if (unread.length === 0)
+        return;
+      log.info(LOG.INJECT, `Injecting urgent notification`, { sessionId, unreadCount: unread.length });
+      const notification = urgentNotification(unread.length);
+      const syntheticMessage = {
+        info: {
+          id: "msg_iam_" + Date.now(),
+          sessionID: sessionId,
+          role: "user",
+          time: { created: Date.now() },
+          agent: lastUserMsg.info.agent || "code",
+          model: lastUserMsg.info.model
+        },
+        parts: [
+          {
+            id: "prt_iam_" + Date.now(),
+            sessionID: sessionId,
+            messageID: "msg_iam_" + Date.now(),
+            type: "text",
+            text: notification
+          }
+        ]
+      };
+      output.messages.push(syntheticMessage);
+    }
+  };
+};
+var inbox_default = plugin;
+export {
+  inbox_default as default
+};

package/dist/logger.d.ts

@@ -0,0 +1,14 @@
+export declare const log: {
+    debug: (category: string, message: string, data?: unknown) => void;
+    info: (category: string, message: string, data?: unknown) => void;
+    warn: (category: string, message: string, data?: unknown) => void;
+    error: (category: string, message: string, data?: unknown) => void;
+};
+export declare const LOG: {
+    readonly TOOL: "TOOL";
+    readonly MESSAGE: "MESSAGE";
+    readonly SESSION: "SESSION";
+    readonly HOOK: "HOOK";
+    readonly INJECT: "INJECT";
+};
+//# sourceMappingURL=logger.d.ts.map

package/dist/logger.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"logger.d.ts","sourceRoot":"","sources":["../logger.ts"],"names":[],"mappings":"AAuCA,eAAO,MAAM,GAAG;sBACI,MAAM,WAAW,MAAM,SAAS,OAAO;qBAGxC,MAAM,WAAW,MAAM,SAAS,OAAO;qBAGvC,MAAM,WAAW,MAAM,SAAS,OAAO;sBAGtC,MAAM,WAAW,MAAM,SAAS,OAAO;CAE1D,CAAA;AAGD,eAAO,MAAM,GAAG;;;;;;CAMN,CAAA"}

package/dist/prompt.d.ts

@@ -0,0 +1,22 @@
+export declare const TOOL_DESCRIPTION = "Inter-agent messaging. Use this to communicate with other parallel agents (task tools).\n\nActions:\n- \"sessions\": Show session IDs of agents you can message\n- \"read\": Read all your messages (marks them as read)\n- \"write\": Send a message to another agent";
+export declare const ARG_DESCRIPTIONS: {
+    readonly action: "Action to perform";
+    readonly to: "Recipient session ID (required for 'write')";
+    readonly message: "Message content (required for 'write')";
+};
+export declare const SESSIONS_EMPTY = "No other agents available yet.\n\nAgents will appear here when:\n- Parallel tasks are spawned by the same parent\n- Another agent sends you a message";
+export declare function sessionsResult(agents: string[]): string;
+export declare const READ_EMPTY = "No messages in your iam.";
+export declare function readResult(messages: {
+    from: string;
+    body: string;
+    timestamp: number;
+    read: boolean;
+}[], unreadCount: number): string;
+export declare const WRITE_MISSING_TO = "Error: 'to' is required. Use: iam write --to <session_id> --message \"...\"";
+export declare const WRITE_MISSING_MESSAGE = "Error: 'message' is required. Use: iam write --to <session_id> --message \"...\"";
+export declare function writeResult(to: string, messageId: string): string;
+export declare function unknownAction(action: string): string;
+export declare const SYSTEM_PROMPT = "\n# Inter-Agent Messaging\n\nYou have access to an `iam` tool for communicating with other parallel agents.\n\nCommands:\n- `iam sessions` - See agents you can message\n- `iam read` - Read all your messages\n- `iam write --to <session_id> --message \"...\"` - Send a message\n\nCheck your iam when notified about new messages.\n";
+export declare function urgentNotification(unreadCount: number): string;
+//# sourceMappingURL=prompt.d.ts.map

package/dist/prompt.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"prompt.d.ts","sourceRoot":"","sources":["../prompt.ts"],"names":[],"mappings":"AAIA,eAAO,MAAM,gBAAgB,2QAKc,CAAC;AAE5C,eAAO,MAAM,gBAAgB;;;;CAInB,CAAC;AAMX,eAAO,MAAM,cAAc,0JAIS,CAAC;AAErC,wBAAgB,cAAc,CAAC,MAAM,EAAE,MAAM,EAAE,GAAG,MAAM,CAOvD;AAED,eAAO,MAAM,UAAU,6BAA6B,CAAC;AAErD,wBAAgB,UAAU,CACxB,QAAQ,EAAE;IAAC,IAAI,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,MAAM,CAAC;IAAC,SAAS,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,OAAO,CAAA;CAAC,EAAE,EAC1E,WAAW,EAAE,MAAM,GAClB,MAAM,CAeR;AAED,eAAO,MAAM,gBAAgB,gFAA8E,CAAC;AAC5G,eAAO,MAAM,qBAAqB,qFAAmF,CAAC;AAEtH,wBAAgB,WAAW,CAAC,EAAE,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,GAAG,MAAM,CAEjE;AAED,wBAAgB,aAAa,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,CAEpD;AAMD,eAAO,MAAM,aAAa,6UAWzB,CAAC;AAMF,wBAAgB,kBAAkB,CAAC,WAAW,EAAE,MAAM,GAAG,MAAM,CAK9D"}

package/package.json

@@ -0,0 +1,40 @@
+{
+  "name": "@spoons-and-mirrors/iam",
+  "version": "0.1.0",
+  "description": "Inter-agent messaging for OpenCode parallel subagents",
+  "type": "module",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist",
+    "README.md"
+  ],
+  "scripts": {
+    "build": "bun build ./index.ts --outdir ./dist --target node --format esm --external '@opencode-ai/plugin' && tsc --emitDeclarationOnly",
+    "prepublishOnly": "bun run build",
+    "typecheck": "tsc --noEmit"
+  },
+  "keywords": [
+    "opencode",
+    "plugin",
+    "inter-agent",
+    "messaging",
+    "subagent"
+  ],
+  "license": "MIT",
+  "peerDependencies": {
+    "@opencode-ai/plugin": ">=0.13.7"
+  },
+  "devDependencies": {
+    "@opencode-ai/plugin": "^1.0.143",
+    "@types/node": "^24.10.1",
+    "bun-types": "^1.3.5",
+    "typescript": "^5.9.3"
+  }
+}