@spoons-and-mirrors/iam 0.1.4 → 0.1.6

package/README.md

@@ -1,42 +1,100 @@
-# IAM Plugin for OpenCode
+# IAM (Inter-Agent Messaging)
 
-Lets parallel subagents talk to each other. No configuration needed — just install and it works.
+Enable parallel agents communication for opencode
 
-## What It Does
-
-When you spawn multiple agents with the `task` tool, they can:
-- **Announce** what they're working on (and see all parallel agents)
-- **Broadcast** messages to one, some, or all agents
-- Get **notified** when new messages arrive
+`@spoons-and-mirrors/iam@latest`
 
 ## How It Works
 
-Agents get friendly names (agentA, agentB, ...) and automatically discover each other.
+Parallel agents they can send messages to each other using the `broadcast` tool. Messages are relayed to the proper agent's context.
+
+```mermaid
+sequenceDiagram
+    participant Parent as Parent Session
+    participant A as AgentA
+    participant B as AgentB
+
+    Parent->>A: spawn task
+    Parent->>B: spawn task
+
+    Note over A,B: Both agents auto-register on first LLM call
+
+    A->>B: broadcast(recipient="agentB", message="Question?")
+
+    Note over B: Receives message
+    Note over B: Responds
+
+    B->>A: broadcast(recipient="agentA", reply_to=[1], message="Answer!")
+
+    Note over A: Receives reply
+    Note over B: Tool output shows both reply and handled message
+    Note over B: Remove message from inbox
+```
+
+## The `broadcast` Tool
+
+```
+broadcast(message="...")                                 # Send to all agents
+broadcast(recipient="agentB", message="...")             # Send to specific agent
+broadcast(reply_to=[1, 2], message="...")                # Mark messages as handled
+broadcast(recipient="agentA", reply_to=[1], message="...") # Reply and mark handled
+```
+
+### Parameters
+
+| Parameter   | Required | Description                                                          |
+| ----------- | -------- | -------------------------------------------------------------------- |
+| `message`   | Yes      | Your message content                                                 |
+| `recipient` | No       | Target agent(s), comma-separated. Omit to send to all                |
+| `reply_to`  | No       | Array of message IDs to mark as handled (e.g., `[1]` or `[1, 2, 3]`) |
+
+## Receiving Messages
+
+Messages appear as a `broadcast` tool result with structured data:
+
+```json
+{
+  "messages": [
+    { "id": 1, "from": "agentA", "body": "What's the status on the API?" },
+    { "id": 2, "from": "agentA", "body": "Also, can you check the tests?" }
+  ],
+  "agents": ["agentA", "agentC: Working on backend"]
+}
+```
 
-When an agent announces, the response shows all other parallel agents — whether they've announced yet or not. This gives agents instant awareness of who's working alongside them. Agents can re-announce to update their status.
+The `agents` array always shows available agents to message. This is injected even when there are no incoming messages.
 
-When an agent completes their task, they're encouraged to broadcast a completion message so others know.
+Messages persist in the inbox until the agent marks them as handled using `reply_to`.
 
-The plugin injects IAM instructions into the **system prompt** for child sessions only (sessions with a `parentID`).
+## Installation
 
-## Actions
+Add to your OpenCode config:
 
-| Action | Description |
-|--------|-------------|
-| `announce` | Declare what you're working on. Shows all parallel agents. Can re-announce to update. |
-| `read` | Read your inbox (marks messages as read). |
-| `broadcast` | Send a message. Use `to` for specific agent(s), or omit for all. |
+```
+"plugin": ["@spoons-and-mirrors/iam@latest"]
+```
 
-## Examples
+## Example Workflow
 
 ```
-# Announce what you're doing (also shows parallel agents)
-action="announce", message="Refactoring the auth module"
+# Parent spawns two agents to work on different parts of a feature
 
-# Message everyone
-action="broadcast", message="Found a bug in config.ts, heads up"
+AgentA (working on frontend):
+  → broadcast(message="Starting frontend work")
+  → ... does work ...
+  → broadcast(recipient="agentB", message="Need the API schema")
 
-# Message specific agent(s)
-action="broadcast", to="agentA", message="Can you check auth.ts?"
-action="broadcast", to="agentA,agentC", message="Sync up on API changes"
+AgentB (working on backend):
+  → broadcast(message="Starting backend work")
+  → ... sees AgentA's question in inbox ...
+  → broadcast(recipient="agentA", reply_to=[1], message="Here's the schema: {...}")
+
+AgentA:
+  → ... sees AgentB's response in inbox ...
+  → broadcast(reply_to=[1], message="Got it, thanks!")
 ```
+
+## Notes
+
+- Agents are assigned aliases automatically: `agentA`, `agentB`, `agentC`, etc.
+- Logs are written to `.logs/iam.log` for debugging

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../index.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,qBAAqB,CAAA;AAqLjD,QAAA,MAAM,MAAM,EAAE,MAiLb,CAAA;AAED,eAAe,MAAM,CAAA"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../index.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,qBAAqB,CAAC;AAijBlD,QAAA,MAAM,MAAM,EAAE,MAwTb,CAAC;AAEF,eAAe,MAAM,CAAC"}

package/dist/index.js

@@ -2,147 +2,122 @@
 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:
-- "announce": Announce what you're working on (do this first!). Shows all parallel agents. You can re-announce to update your status.
-- "read": Read your messages (marks them as read)
-- "broadcast": Send a message (requires 'message', optional 'to')`;
-var ARG_DESCRIPTIONS = {
-  action: "Action to perform",
-  to: "Recipient(s): 'agentA', 'agentA,agentC', or 'all' (default: all)",
-  message: "Your announcement or message content"
-};
-function formatAgentList(agents) {
+var BROADCAST_DESCRIPTION = `Communicate with other parallel agents. Use 'recipient' for specific agent(s), or omit to message all. Use 'reply_to' to mark messages as handled.`;
+function broadcastResult(alias, recipients, parallelAgents, handledMessages) {
   const lines = [];
-  for (const agent of agents) {
-    if (agent.description) {
-      lines.push(`• ${agent.alias} is working on: ${agent.description}`);
-    } else {
-      lines.push(`• ${agent.alias} is running (hasn't announced yet)`);
+  lines.push(`You are: ${alias}`);
+  lines.push(``);
+  if (parallelAgents.length > 0) {
+    lines.push(`Available agents to message:`);
+    for (const agent of parallelAgents) {
+      if (agent.description) {
+        lines.push(`  - ${agent.alias}: ${agent.description}`);
+      } else {
+        lines.push(`  - ${agent.alias}`);
+      }
     }
-  }
-  return lines;
-}
-function readResult(alias, messages, unreadCount, hasAnnounced) {
-  const lines = [`You are: ${alias}`, ``];
-  if (messages.length === 0) {
-    lines.push(`No messages in your inbox.`);
   } else {
-    lines.push(`Your inbox (${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: use action="broadcast" with to="<sender>" and message="..."`);
+    lines.push(`No other agents available yet.`);
   }
-  if (!hasAnnounced) {
+  if (recipients.length > 0) {
     lines.push(``);
-    lines.push(`IMPORTANT: You MUST use action="announce" to declare what you're working on before continuing.`);
+    const recipientStr = recipients.length === 1 ? recipients[0] : recipients.join(", ");
+    lines.push(`Message sent to: ${recipientStr}`);
   }
-  return lines.join(`
-`);
-}
-function announceResult(alias, parallelAgents) {
-  const lines = [
-    `Announced! Other agents will see your description when they call announce.`,
-    ``,
-    `You are: ${alias}`
-  ];
-  if (parallelAgents.length > 0) {
+  if (handledMessages.length > 0) {
     lines.push(``);
-    lines.push(`--- Parallel Agents ---`);
-    lines.push(...formatAgentList(parallelAgents));
-    lines.push(``);
-    lines.push(`Use action="broadcast" to coordinate with them.`);
-  } else {
-    lines.push(``);
-    lines.push(`No other agents running yet.`);
+    lines.push(`Marked as handled: ${handledMessages.length} message(s)`);
+    for (const msg of handledMessages) {
+      const preview = msg.body.length > 80 ? msg.body.substring(0, 80) + "..." : msg.body;
+      lines.push(`  #${msg.id} from ${msg.from}: "${preview}"`);
+    }
   }
   return lines.join(`
 `);
 }
-var BROADCAST_MISSING_MESSAGE = `Error: 'message' parameter is required for action="broadcast".`;
-function broadcastUnknownRecipient(to, known) {
-  const list = known.length > 0 ? `Known agents: ${known.join(", ")}` : "No agents available yet.";
-  return `Error: Unknown recipient "${to}". ${list}`;
-}
-function broadcastResult(recipients, messageId) {
-  const recipientStr = recipients.length === 1 ? recipients[0] : recipients.join(", ");
-  return `Message sent!
-
-To: ${recipientStr}
-Message ID: ${messageId}
-
-Recipients will be notified.`;
+var BROADCAST_MISSING_MESSAGE = `Error: 'message' parameter is required.`;
+var BROADCAST_SELF_MESSAGE = `Warning: You cannot send a message to yourself. The target alias is your own alias. Choose a different recipient.`;
+function broadcastMessageTooLong(length, maxLength) {
+  return `Error: Message too long (${length} chars). Maximum allowed: ${maxLength} chars.`;
 }
-function unknownAction(action) {
-  return `Unknown action: ${action}. Valid actions: announce, read, broadcast`;
+function broadcastUnknownRecipient(recipient, known) {
+  const list = known.length > 0 ? `Known agents: ${known.join(", ")}` : "No agents available yet.";
+  return `Error: Unknown recipient "${recipient}". ${list}`;
 }
 var SYSTEM_PROMPT = `
 <instructions tool="iam">
 # Inter-Agent Messaging
 
-You have access to an \`iam\` tool for communicating with other parallel agents.
+Use \`broadcast\` to communicate with other parallel agents.
 
-Usage:
-- action="announce", message="..." - Announce what you're working on (do this first!)
-- action="read" - Read your messages
-- action="broadcast", message="..." - Message all agents
-- action="broadcast", to="agentA", message="..." - Message specific agent(s)
+## IMPORTANT: Broadcast Immediately on Start
+Call \`broadcast(message="...")\` as your FIRST action to announce yourself and discover other agents. The tool result will show all available agents you can message.
 
-At the start of your task, use announce to let other agents know what you're doing.
-You can re-announce to update your status as your task evolves.
-Check your inbox when notified about new messages.
+## Sending Messages
+- \`broadcast(message="...")\` → send to all agents
+- \`broadcast(recipient="agentB", message="...")\` → send to specific agent
 
-When you complete your task, broadcast to all: "Done. Here's what I found/did: ..."
+## Receiving Messages
+Incoming messages appear as \`broadcast\` tool results with a \`messages\` array:
+\`\`\`
+{ messages: [{ id: 1, from: "agentA", body: "..." }, ...] }
+\`\`\`
+
+Use \`reply_to\` to mark messages as handled (they persist until you do):
+- \`broadcast(recipient="agentA", reply_to=[1], message="...")\`
+- \`broadcast(recipient="agentA", reply_to=[1, 2, 3], message="...")\`
 </instructions>
 `;
-function urgentNotification(unreadCount) {
-  return `<system-reminder priority="critical">
-URGENT: You have ${unreadCount} unread message(s) in your IAM inbox.
-Use the iam tool with action="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 __dirname = "/home/spoon/.config/opencode/plugin/iam";
-var IS_DEV = fs.existsSync(path.join(__dirname, "..", ".git"));
 var LOG_DIR = path.join(process.cwd(), ".logs");
 var LOG_FILE = path.join(LOG_DIR, "iam.log");
-if (IS_DEV) {
+var WRITE_INTERVAL_MS = 100;
+var logBuffer = [];
+var writeScheduled = false;
+try {
+  if (!fs.existsSync(LOG_DIR)) {
+    fs.mkdirSync(LOG_DIR, { recursive: true });
+  }
+  fs.writeFileSync(LOG_FILE, "");
+} catch {}
+function formatTimestamp() {
+  return new Date().toISOString();
+}
+async function flushLogs() {
+  if (logBuffer.length === 0) {
+    writeScheduled = false;
+    return;
+  }
+  const toWrite = logBuffer.join("");
+  logBuffer = [];
+  writeScheduled = false;
   try {
-    if (!fs.existsSync(LOG_DIR)) {
-      fs.mkdirSync(LOG_DIR, { recursive: true });
-    }
-    fs.writeFileSync(LOG_FILE, "");
+    await fs.promises.appendFile(LOG_FILE, toWrite);
   } catch {}
 }
-function formatTimestamp() {
-  return new Date().toISOString();
+function scheduleFlush() {
+  if (!writeScheduled) {
+    writeScheduled = true;
+    setTimeout(flushLogs, WRITE_INTERVAL_MS);
+  }
 }
 function writeLog(level, category, message, data) {
-  if (!IS_DEV)
-    return;
   const timestamp = formatTimestamp();
   const dataStr = data !== undefined ? ` | ${JSON.stringify(data)}` : "";
   const logLine = `[${timestamp}] [${level}] [${category}] ${message}${dataStr}
 `;
-  try {
-    fs.appendFileSync(LOG_FILE, logLine);
-  } catch {}
+  logBuffer.push(logLine);
+  scheduleFlush();
 }
 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)
+  error: (category, message, data) => writeLog("ERROR", category, message, data),
+  flush: flushLogs
 };
 var LOG = {
   TOOL: "TOOL",
@@ -153,18 +128,76 @@ var LOG = {
 };
 
 // index.ts
+var CHAR_CODE_A = 65;
+var ALPHABET_SIZE = 26;
+var MAX_DESCRIPTION_LENGTH = 100;
+var MESSAGE_TTL_MS = 30 * 60 * 1000;
+var UNHANDLED_TTL_MS = 2 * 60 * 60 * 1000;
+var MAX_INBOX_SIZE = 100;
+var PARENT_CACHE_TTL_MS = 5 * 60 * 1000;
+var CLEANUP_INTERVAL_MS = 60 * 1000;
+var DEFAULT_MODEL_ID = "gpt-4o-2024-08-06";
+var DEFAULT_PROVIDER_ID = "openai";
+var MAX_MESSAGE_LENGTH = 1e4;
 var inboxes = new Map;
+var sessionMsgCounter = new Map;
 var activeSessions = new Set;
 var sessionToAlias = new Map;
 var aliasToSession = new Map;
 var agentDescriptions = new Map;
 var nextAgentIndex = 0;
-var instructedSessions = new Set;
+var registeringSessionsLock = new Set;
 var sessionParentCache = new Map;
+function cleanupExpiredMessages() {
+  const now = Date.now();
+  let totalRemoved = 0;
+  for (const [sessionId, messages] of inboxes) {
+    const before = messages.length;
+    const filtered = messages.filter((m) => {
+      if (m.handled) {
+        return now - m.timestamp < MESSAGE_TTL_MS;
+      }
+      return now - m.timestamp < UNHANDLED_TTL_MS;
+    });
+    if (filtered.length > MAX_INBOX_SIZE) {
+      const unhandled = filtered.filter((m) => !m.handled);
+      const handled = filtered.filter((m) => m.handled);
+      handled.sort((a, b) => b.timestamp - a.timestamp);
+      if (unhandled.length > MAX_INBOX_SIZE) {
+        unhandled.sort((a, b) => b.timestamp - a.timestamp);
+        inboxes.set(sessionId, unhandled.slice(0, MAX_INBOX_SIZE));
+        totalRemoved += before - MAX_INBOX_SIZE;
+      } else {
+        const kept = [
+          ...unhandled,
+          ...handled.slice(0, MAX_INBOX_SIZE - unhandled.length)
+        ];
+        inboxes.set(sessionId, kept);
+        totalRemoved += before - kept.length;
+      }
+    } else {
+      inboxes.set(sessionId, filtered);
+      totalRemoved += before - filtered.length;
+    }
+    if (inboxes.get(sessionId).length === 0) {
+      inboxes.delete(sessionId);
+    }
+  }
+  for (const [sessionId, cached] of sessionParentCache) {
+    if (now - cached.cachedAt > PARENT_CACHE_TTL_MS) {
+      sessionParentCache.delete(sessionId);
+    }
+  }
+  if (totalRemoved > 0) {
+    log.debug(LOG.MESSAGE, `Cleanup removed ${totalRemoved} expired messages`);
+  }
+}
+setInterval(cleanupExpiredMessages, CLEANUP_INTERVAL_MS);
 function getNextAlias() {
-  const letter = String.fromCharCode(65 + nextAgentIndex % 26);
-  const suffix = nextAgentIndex >= 26 ? Math.floor(nextAgentIndex / 26).toString() : "";
+  const index = nextAgentIndex;
   nextAgentIndex++;
+  const letter = String.fromCharCode(CHAR_CODE_A + index % ALPHABET_SIZE);
+  const suffix = index >= ALPHABET_SIZE ? Math.floor(index / ALPHABET_SIZE).toString() : "";
   return `agent${letter}${suffix}`;
 }
 function getAlias(sessionId) {
@@ -172,22 +205,28 @@ function getAlias(sessionId) {
 }
 function setDescription(sessionId, description) {
   const alias = getAlias(sessionId);
-  agentDescriptions.set(alias, description);
-  log.info(LOG.SESSION, `Agent announced`, { alias, description });
+  const truncated = description.substring(0, MAX_DESCRIPTION_LENGTH);
+  agentDescriptions.set(alias, truncated);
+  log.info(LOG.SESSION, `Agent announced`, { alias, description: truncated });
 }
 function getDescription(alias) {
   return agentDescriptions.get(alias);
 }
-function hasAnnounced(sessionId) {
-  const alias = getAlias(sessionId);
-  return agentDescriptions.has(alias);
-}
-function resolveAlias(aliasOrSessionId) {
+function resolveAlias(aliasOrSessionId, parentId) {
+  if (aliasOrSessionId === "parent" && parentId) {
+    return parentId;
+  }
   return aliasToSession.get(aliasOrSessionId) || (activeSessions.has(aliasOrSessionId) ? aliasOrSessionId : undefined);
 }
 function generateId() {
   return Math.random().toString(36).substring(2, 10);
 }
+function getNextMsgIndex(sessionId) {
+  const current = sessionMsgCounter.get(sessionId) || 0;
+  const next = current + 1;
+  sessionMsgCounter.set(sessionId, next);
+  return next;
+}
 function getInbox(sessionId) {
   if (!inboxes.has(sessionId)) {
     inboxes.set(sessionId, []);
@@ -197,152 +236,326 @@ function getInbox(sessionId) {
 function sendMessage(from, to, body) {
   const message = {
     id: generateId(),
+    msgIndex: getNextMsgIndex(to),
     from,
     to,
     body,
     timestamp: Date.now(),
-    read: false
+    handled: false
   };
-  getInbox(to).push(message);
-  log.info(LOG.MESSAGE, `Message sent`, { id: message.id, from, to, bodyLength: body.length });
+  const queue = getInbox(to);
+  if (queue.length >= MAX_INBOX_SIZE) {
+    const handledIndex = queue.findIndex((m) => m.handled);
+    if (handledIndex !== -1) {
+      queue.splice(handledIndex, 1);
+    } else {
+      queue.shift();
+    }
+    log.warn(LOG.MESSAGE, `Queue full, removed oldest message`, { to });
+  }
+  queue.push(message);
+  log.info(LOG.MESSAGE, `Message sent`, {
+    id: message.id,
+    msgIndex: message.msgIndex,
+    from,
+    to,
+    bodyLength: body.length
+  });
   return message;
 }
-function getUnreadMessages(sessionId) {
-  return getInbox(sessionId).filter((m) => !m.read);
-}
-function getAllMessages(sessionId) {
-  return getInbox(sessionId);
+function getUnhandledMessages(sessionId) {
+  return getInbox(sessionId).filter((m) => !m.handled);
 }
-function markAllRead(sessionId) {
-  const iam = getInbox(sessionId);
-  const unreadCount = iam.filter((m) => !m.read).length;
-  for (const msg of iam) {
-    msg.read = true;
+function markMessagesAsHandled(sessionId, msgIndices) {
+  const queue = getInbox(sessionId);
+  const handled = [];
+  for (const msg of queue) {
+    if (msgIndices.includes(msg.msgIndex) && !msg.handled) {
+      msg.handled = true;
+      handled.push({
+        id: msg.msgIndex,
+        from: msg.from,
+        body: msg.body
+      });
+      log.info(LOG.MESSAGE, `Message marked as handled`, {
+        sessionId,
+        msgIndex: msg.msgIndex,
+        from: msg.from
+      });
+    }
   }
-  log.info(LOG.MESSAGE, `Marked all read`, { sessionId, count: unreadCount });
+  return handled;
 }
-function getKnownAgents(sessionId) {
+function getKnownAliases(sessionId) {
+  const selfAlias = sessionToAlias.get(sessionId);
   const agents = [];
-  for (const id of activeSessions) {
-    if (id !== sessionId) {
-      agents.push(getAlias(id));
+  for (const alias of aliasToSession.keys()) {
+    if (alias !== selfAlias) {
+      agents.push(alias);
     }
   }
   return agents;
 }
 function getParallelAgents(sessionId) {
-  return getKnownAgents(sessionId).map((alias) => ({
-    alias,
-    description: getDescription(alias)
-  }));
+  const selfAlias = sessionToAlias.get(sessionId);
+  const agents = [];
+  for (const [alias, sessId] of aliasToSession.entries()) {
+    if (alias !== selfAlias) {
+      agents.push({
+        alias,
+        description: getDescription(alias)
+      });
+    }
+  }
+  return agents;
 }
 function registerSession(sessionId) {
-  if (!activeSessions.has(sessionId)) {
-    activeSessions.add(sessionId);
-    const alias = getNextAlias();
-    sessionToAlias.set(sessionId, alias);
-    aliasToSession.set(alias, sessionId);
-    log.info(LOG.SESSION, `Session registered`, { sessionId, alias, totalSessions: activeSessions.size });
+  if (activeSessions.has(sessionId)) {
+    return;
+  }
+  if (registeringSessionsLock.has(sessionId)) {
+    return;
+  }
+  registeringSessionsLock.add(sessionId);
+  try {
+    if (!activeSessions.has(sessionId)) {
+      activeSessions.add(sessionId);
+      const alias = getNextAlias();
+      sessionToAlias.set(sessionId, alias);
+      aliasToSession.set(alias, sessionId);
+      log.info(LOG.SESSION, `Session registered`, {
+        sessionId,
+        alias,
+        totalSessions: activeSessions.size
+      });
+    }
+  } finally {
+    registeringSessionsLock.delete(sessionId);
   }
 }
 async function getParentId(client, sessionId) {
-  if (sessionParentCache.has(sessionId)) {
-    return sessionParentCache.get(sessionId);
+  const now = Date.now();
+  const cached = sessionParentCache.get(sessionId);
+  if (cached && now - cached.cachedAt < PARENT_CACHE_TTL_MS) {
+    return cached.value;
   }
   try {
     const response = await client.session.get({ path: { id: sessionId } });
     const parentId = response.data?.parentID || null;
-    sessionParentCache.set(sessionId, parentId);
+    sessionParentCache.set(sessionId, { value: parentId, cachedAt: now });
     log.debug(LOG.SESSION, `Looked up parentID`, { sessionId, parentId });
     return parentId;
   } catch (e) {
-    log.warn(LOG.SESSION, `Failed to get session info`, { sessionId, error: String(e) });
-    sessionParentCache.set(sessionId, null);
+    log.warn(LOG.SESSION, `Failed to get session info`, {
+      sessionId,
+      error: String(e)
+    });
+    sessionParentCache.set(sessionId, {
+      value: null,
+      cachedAt: now - PARENT_CACHE_TTL_MS + 60000
+    });
     return null;
   }
 }
+function createInboxMessage(sessionId, messages, baseUserMessage) {
+  const now = Date.now();
+  const userInfo = baseUserMessage.info;
+  const inboxMsgs = messages.map((m) => ({
+    id: m.msgIndex,
+    from: m.from,
+    body: m.body
+  }));
+  const assistantMessageId = `msg_broadcast_${now}`;
+  const partId = `prt_broadcast_${now}`;
+  const callId = `call_broadcast_${now}`;
+  log.debug(LOG.MESSAGE, `Creating bundled inbox message`, {
+    sessionId,
+    messageCount: messages.length,
+    msgIndices: messages.map((m) => m.msgIndex)
+  });
+  const result = {
+    info: {
+      id: assistantMessageId,
+      sessionID: sessionId,
+      role: "assistant",
+      agent: userInfo.agent || "code",
+      parentID: userInfo.id,
+      modelID: userInfo.model?.modelID || DEFAULT_MODEL_ID,
+      providerID: userInfo.model?.providerID || DEFAULT_PROVIDER_ID,
+      mode: "default",
+      path: { cwd: "/", root: "/" },
+      time: { created: now, completed: now },
+      cost: 0,
+      tokens: {
+        input: 0,
+        output: 0,
+        reasoning: 0,
+        cache: { read: 0, write: 0 }
+      }
+    },
+    parts: [
+      {
+        id: partId,
+        sessionID: sessionId,
+        messageID: assistantMessageId,
+        type: "tool",
+        callID: callId,
+        tool: "broadcast",
+        state: {
+          status: "completed",
+          input: { messages: inboxMsgs },
+          output: `${messages.length} message(s)`,
+          title: `Inbox (${messages.length} messages)`,
+          metadata: {
+            incoming_message: true,
+            message_count: messages.length
+          },
+          time: { start: now, end: now }
+        }
+      }
+    ]
+  };
+  if (userInfo.variant !== undefined) {
+    result.info.variant = userInfo.variant;
+  }
+  return result;
+}
 var plugin = async (ctx) => {
   log.info(LOG.HOOK, "Plugin initialized");
   const client = ctx.client;
   return {
     tool: {
-      iam: tool({
-        description: TOOL_DESCRIPTION,
+      broadcast: tool({
+        description: BROADCAST_DESCRIPTION,
         args: {
-          action: tool.schema.enum(["read", "broadcast", "announce"]).describe(ARG_DESCRIPTIONS.action),
-          to: tool.schema.string().optional().describe(ARG_DESCRIPTIONS.to),
-          message: tool.schema.string().optional().describe(ARG_DESCRIPTIONS.message)
+          recipient: tool.schema.string().optional().describe("Target agent(s), comma-separated. Omit to send to all."),
+          message: tool.schema.string().describe("Your message"),
+          reply_to: tool.schema.array(tool.schema.number()).optional().describe("Message IDs to mark as handled (e.g., [1, 2, 3])")
         },
         async execute(args, context) {
           const sessionId = context.sessionID;
+          const isFirstCall = !activeSessions.has(sessionId);
           registerSession(sessionId);
           const alias = getAlias(sessionId);
-          const announced = hasAnnounced(sessionId);
-          log.debug(LOG.TOOL, `iam action: ${args.action}`, { sessionId, alias, args });
-          switch (args.action) {
-            case "read": {
-              const messages = getAllMessages(sessionId);
-              const unreadCount = messages.filter((m) => !m.read).length;
-              log.debug(LOG.TOOL, `read inbox`, { alias, total: messages.length, unread: unreadCount });
-              markAllRead(sessionId);
-              return readResult(alias, messages, unreadCount, announced);
+          if (!args.message) {
+            log.warn(LOG.TOOL, `broadcast missing 'message'`, { alias });
+            return BROADCAST_MISSING_MESSAGE;
+          }
+          if (args.message.length > MAX_MESSAGE_LENGTH) {
+            log.warn(LOG.TOOL, `broadcast message too long`, {
+              alias,
+              length: args.message.length
+            });
+            return broadcastMessageTooLong(args.message.length, MAX_MESSAGE_LENGTH);
+          }
+          if (isFirstCall) {
+            setDescription(sessionId, args.message);
+          }
+          log.debug(LOG.TOOL, `broadcast called`, {
+            sessionId,
+            alias,
+            recipient: args.recipient,
+            reply_to: args.reply_to,
+            messageLength: args.message.length,
+            isFirstCall
+          });
+          let handledMessages = [];
+          if (args.reply_to && args.reply_to.length > 0) {
+            handledMessages = markMessagesAsHandled(sessionId, args.reply_to);
+            log.info(LOG.TOOL, `Handled messages via reply_to`, {
+              alias,
+              requested: args.reply_to,
+              actuallyHandled: handledMessages.length
+            });
+          }
+          const knownAgents = getKnownAliases(sessionId);
+          const parallelAgents = getParallelAgents(sessionId);
+          let targetAliases;
+          if (!args.recipient) {
+            targetAliases = knownAgents;
+          } else {
+            targetAliases = args.recipient.split(",").map((s) => s.trim()).filter(Boolean);
+          }
+          if (targetAliases.length === 0) {
+            log.info(LOG.TOOL, `No recipients, returning agent info`, {
+              alias
+            });
+            return broadcastResult(alias, [], parallelAgents, handledMessages);
+          }
+          const parentId = await getParentId(client, sessionId);
+          const recipientSessions = [];
+          const validTargets = [];
+          for (const targetAlias of targetAliases) {
+            const recipientSessionId = resolveAlias(targetAlias, parentId);
+            if (!recipientSessionId) {
+              log.warn(LOG.TOOL, `broadcast unknown recipient`, {
+                alias,
+                to: targetAlias
+              });
+              return broadcastUnknownRecipient(targetAlias, knownAgents);
             }
-            case "broadcast": {
-              if (!args.message) {
-                log.warn(LOG.TOOL, `broadcast missing 'message'`, { alias });
-                return BROADCAST_MISSING_MESSAGE;
-              }
-              const knownAgents = getKnownAgents(sessionId);
-              let targetAliases;
-              if (!args.to || args.to.toLowerCase() === "all") {
-                targetAliases = knownAgents;
-              } else {
-                targetAliases = args.to.split(",").map((s) => s.trim()).filter(Boolean);
+            if (recipientSessionId === sessionId) {
+              log.warn(LOG.TOOL, `Skipping self-message`, {
+                alias,
+                targetAlias
+              });
+              if (targetAliases.length === 1) {
+                return BROADCAST_SELF_MESSAGE;
               }
-              if (targetAliases.length === 0) {
-                return `No agents to broadcast to. Use action="announce" to see parallel agents.`;
-              }
-              const recipientSessions = [];
-              for (const targetAlias of targetAliases) {
-                const recipientSessionId = resolveAlias(targetAlias);
-                if (!recipientSessionId) {
-                  log.warn(LOG.TOOL, `broadcast unknown recipient`, { alias, to: targetAlias });
-                  return broadcastUnknownRecipient(targetAlias, knownAgents);
-                }
-                recipientSessions.push(recipientSessionId);
-              }
-              let messageId = "";
-              for (const recipientSessionId of recipientSessions) {
-                const msg = sendMessage(alias, recipientSessionId, args.message);
-                messageId = msg.id;
-              }
-              return broadcastResult(targetAliases, messageId);
+              continue;
             }
-            case "announce": {
-              if (!args.message) {
-                log.warn(LOG.TOOL, `announce missing 'message'`, { alias });
-                return `Error: 'message' parameter is required for action="announce". Describe what you're working on.`;
+            recipientSessions.push(recipientSessionId);
+            validTargets.push(targetAlias);
+          }
+          if (recipientSessions.length === 0) {
+            log.info(LOG.TOOL, `No valid recipients after filtering`, {
+              alias
+            });
+            return broadcastResult(alias, [], parallelAgents, handledMessages);
+          }
+          const isTargetingParent = parentId && recipientSessions.includes(parentId);
+          for (const recipientSessionId of recipientSessions) {
+            sendMessage(alias, recipientSessionId, args.message);
+          }
+          if (isTargetingParent) {
+            log.info(LOG.MESSAGE, `Broadcasting to parent session, calling notify_once`, { sessionId, parentId });
+            try {
+              const internalClient = client._client;
+              if (internalClient?.post) {
+                await internalClient.post({
+                  url: `/session/${parentId}/notify_once`,
+                  body: {
+                    text: `[IAM] Message from ${alias}: ${args.message}`
+                  }
+                });
+                log.info(LOG.MESSAGE, `Parent session notified successfully`, {
+                  parentId
+                });
               }
-              setDescription(sessionId, args.message);
-              const parallelAgents = getParallelAgents(sessionId);
-              return announceResult(alias, parallelAgents);
+            } catch (e) {
+              log.warn(LOG.MESSAGE, `Failed to notify parent session`, {
+                parentId,
+                error: String(e)
+              });
             }
-            default:
-              return unknownAction(args.action);
           }
+          return broadcastResult(alias, validTargets, parallelAgents, handledMessages);
         }
       })
     },
     "tool.execute.after": async (input, output) => {
-      log.debug(LOG.HOOK, `tool.execute.after fired`, { tool: input.tool, sessionID: input.sessionID, hasMetadata: !!output.metadata });
+      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 });
+          log.info(LOG.HOOK, `task completed, ensuring session registered`, {
+            newSessionId
+          });
           registerSession(newSessionId);
-        } else {
-          log.warn(LOG.HOOK, `task completed but no session_id in metadata`);
         }
       }
     },
@@ -352,43 +565,63 @@ var plugin = async (ctx) => {
         log.debug(LOG.INJECT, `No sessionID in system.transform input, skipping`);
         return;
       }
-      const parentId = await getParentId(client, sessionId);
-      if (!parentId) {
-        log.debug(LOG.INJECT, `Skipping system prompt injection for main session (no parentID)`, { sessionId });
+      try {
+        const result = await client.session.get({ path: { id: sessionId } });
+        if (!result.data?.parentID) {
+          log.debug(LOG.INJECT, `Session has no parentID (main session), skipping IAM`, {
+            sessionId
+          });
+          return;
+        }
+      } catch (e) {
+        log.debug(LOG.INJECT, `Failed to get session info, skipping IAM`, {
+          sessionId,
+          error: String(e)
+        });
         return;
       }
+      registerSession(sessionId);
       output.system.push(SYSTEM_PROMPT);
-      log.info(LOG.INJECT, `Injected IAM system prompt for child session`, { sessionId, parentId });
+      log.info(LOG.INJECT, `Registered session and injected IAM system prompt`, {
+        sessionId,
+        alias: getAlias(sessionId)
+      });
     },
     "experimental.chat.messages.transform": async (_input, output) => {
       const lastUserMsg = [...output.messages].reverse().find((m) => m.info.role === "user");
-      if (!lastUserMsg)
+      if (!lastUserMsg) {
+        log.debug(LOG.INJECT, `No user message found in transform, skipping IAM injection`);
         return;
+      }
       const sessionId = lastUserMsg.info.sessionID;
-      const unread = getUnreadMessages(sessionId);
-      if (unread.length === 0)
+      const unhandled = getUnhandledMessages(sessionId);
+      log.debug(LOG.INJECT, `Checking for messages in transform`, {
+        sessionId,
+        unhandledCount: unhandled.length
+      });
+      if (unhandled.length === 0) {
         return;
-      log.info(LOG.INJECT, `Injecting urgent notification`, { sessionId, unreadCount: 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: urgentNotification(unread.length)
-          }
-        ]
+      }
+      log.info(LOG.INJECT, `Injecting bundled inbox message`, {
+        sessionId,
+        unhandledCount: unhandled.length,
+        msgIndices: unhandled.map((m) => m.msgIndex)
+      });
+      const inboxMsg = createInboxMessage(sessionId, unhandled, lastUserMsg);
+      output.messages.push(inboxMsg);
+      log.info(LOG.INJECT, `Injected inbox at end of message chain`, {
+        sessionId,
+        messageCount: unhandled.length
+      });
+    },
+    "experimental.config.transform": async (_input, output) => {
+      const experimental = output.experimental ?? {};
+      const existingSubagentTools = experimental.subagent_tools ?? [];
+      output.experimental = {
+        ...experimental,
+        subagent_tools: [...existingSubagentTools, "broadcast"]
       };
-      output.messages.push(syntheticMessage);
+      log.info(LOG.HOOK, `Added 'broadcast' to experimental.subagent_tools`);
     }
   };
 };

package/dist/logger.d.ts

@@ -1,8 +1,14 @@
+/**
+ * Flush buffered logs to file asynchronously
+ */
+declare function flushLogs(): Promise<void>;
 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;
+    /** Force immediate flush (useful before process exit) */
+    flush: typeof flushLogs;
 };
 export declare const LOG: {
     readonly TOOL: "TOOL";
@@ -11,4 +17,5 @@ export declare const LOG: {
     readonly HOOK: "HOOK";
     readonly INJECT: "INJECT";
 };
+export {};
 //# sourceMappingURL=logger.d.ts.map

package/dist/logger.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"logger.d.ts","sourceRoot":"","sources":["../logger.ts"],"names":[],"mappings":"AA+CA,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"}
+{"version":3,"file":"logger.d.ts","sourceRoot":"","sources":["../logger.ts"],"names":[],"mappings":"AAkCA;;GAEG;AACH,iBAAe,SAAS,IAAI,OAAO,CAAC,IAAI,CAAC,CAexC;AA0BD,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;IAGzD,yDAAyD;;CAE1D,CAAC;AAGF,eAAO,MAAM,GAAG;;;;;;CAMN,CAAC"}

package/dist/prompt.d.ts

@@ -1,25 +1,17 @@
-export declare const TOOL_DESCRIPTION = "Inter-agent messaging. Use this to communicate with other parallel agents (task tools).\n\nActions:\n- \"announce\": Announce what you're working on (do this first!). Shows all parallel agents. You can re-announce to update your status.\n- \"read\": Read your messages (marks them as read)\n- \"broadcast\": Send a message (requires 'message', optional 'to')";
-export declare const ARG_DESCRIPTIONS: {
-    readonly action: "Action to perform";
-    readonly to: "Recipient(s): 'agentA', 'agentA,agentC', or 'all' (default: all)";
-    readonly message: "Your announcement or message content";
-};
+export declare const BROADCAST_DESCRIPTION = "Communicate with other parallel agents. Use 'recipient' for specific agent(s), or omit to message all. Use 'reply_to' to mark messages as handled.";
 export interface ParallelAgent {
     alias: string;
     description?: string;
 }
-export declare function formatAgentList(agents: ParallelAgent[]): string[];
-export declare function readResult(alias: string, messages: {
+export interface HandledMessage {
+    id: number;
     from: string;
     body: string;
-    timestamp: number;
-    read: boolean;
-}[], unreadCount: number, hasAnnounced: boolean): string;
-export declare function announceResult(alias: string, parallelAgents: ParallelAgent[]): string;
-export declare const BROADCAST_MISSING_MESSAGE = "Error: 'message' parameter is required for action=\"broadcast\".";
-export declare function broadcastUnknownRecipient(to: string, known: string[]): string;
-export declare function broadcastResult(recipients: string[], messageId: string): string;
-export declare function unknownAction(action: string): string;
-export declare const SYSTEM_PROMPT = "\n<instructions tool=\"iam\">\n# Inter-Agent Messaging\n\nYou have access to an `iam` tool for communicating with other parallel agents.\n\nUsage:\n- action=\"announce\", message=\"...\" - Announce what you're working on (do this first!)\n- action=\"read\" - Read your messages\n- action=\"broadcast\", message=\"...\" - Message all agents\n- action=\"broadcast\", to=\"agentA\", message=\"...\" - Message specific agent(s)\n\nAt the start of your task, use announce to let other agents know what you're doing.\nYou can re-announce to update your status as your task evolves.\nCheck your inbox when notified about new messages.\n\nWhen you complete your task, broadcast to all: \"Done. Here's what I found/did: ...\"\n</instructions>\n";
-export declare function urgentNotification(unreadCount: number): string;
+}
+export declare function broadcastResult(alias: string, recipients: string[], parallelAgents: ParallelAgent[], handledMessages: HandledMessage[]): string;
+export declare const BROADCAST_MISSING_MESSAGE = "Error: 'message' parameter is required.";
+export declare const BROADCAST_SELF_MESSAGE = "Warning: You cannot send a message to yourself. The target alias is your own alias. Choose a different recipient.";
+export declare function broadcastMessageTooLong(length: number, maxLength: number): string;
+export declare function broadcastUnknownRecipient(recipient: string, known: string[]): string;
+export declare const SYSTEM_PROMPT = "\n<instructions tool=\"iam\">\n# Inter-Agent Messaging\n\nUse `broadcast` to communicate with other parallel agents.\n\n## IMPORTANT: Broadcast Immediately on Start\nCall `broadcast(message=\"...\")` as your FIRST action to announce yourself and discover other agents. The tool result will show all available agents you can message.\n\n## Sending Messages\n- `broadcast(message=\"...\")` \u2192 send to all agents\n- `broadcast(recipient=\"agentB\", message=\"...\")` \u2192 send to specific agent\n\n## Receiving Messages\nIncoming messages appear as `broadcast` tool results with a `messages` array:\n```\n{ messages: [{ id: 1, from: \"agentA\", body: \"...\" }, ...] }\n```\n\nUse `reply_to` to mark messages as handled (they persist until you do):\n- `broadcast(recipient=\"agentA\", reply_to=[1], message=\"...\")`\n- `broadcast(recipient=\"agentA\", reply_to=[1, 2, 3], message=\"...\")`\n</instructions>\n";
 //# sourceMappingURL=prompt.d.ts.map

package/dist/prompt.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"prompt.d.ts","sourceRoot":"","sources":["../prompt.ts"],"names":[],"mappings":"AAIA,eAAO,MAAM,gBAAgB,2WAKqC,CAAC;AAEnE,eAAO,MAAM,gBAAgB;;;;CAInB,CAAC;AAMX,MAAM,WAAW,aAAa;IAC5B,KAAK,EAAE,MAAM,CAAC;IACd,WAAW,CAAC,EAAE,MAAM,CAAC;CACtB;AAMD,wBAAgB,eAAe,CAAC,MAAM,EAAE,aAAa,EAAE,GAAG,MAAM,EAAE,CAUjE;AAED,wBAAgB,UAAU,CACxB,KAAK,EAAE,MAAM,EACb,QAAQ,EAAE;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,MAAM,CAAC;IAAC,SAAS,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,OAAO,CAAA;CAAE,EAAE,EAC5E,WAAW,EAAE,MAAM,EACnB,YAAY,EAAE,OAAO,GACpB,MAAM,CA0BR;AAED,wBAAgB,cAAc,CAAC,KAAK,EAAE,MAAM,EAAE,cAAc,EAAE,aAAa,EAAE,GAAG,MAAM,CAmBrF;AAED,eAAO,MAAM,yBAAyB,qEAAmE,CAAC;AAE1G,wBAAgB,yBAAyB,CAAC,EAAE,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,EAAE,GAAG,MAAM,CAG7E;AAED,wBAAgB,eAAe,CAAC,UAAU,EAAE,MAAM,EAAE,EAAE,SAAS,EAAE,MAAM,GAAG,MAAM,CAG/E;AAED,wBAAgB,aAAa,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,CAEpD;AAMD,eAAO,MAAM,aAAa,ouBAkBzB,CAAC;AAMF,wBAAgB,kBAAkB,CAAC,WAAW,EAAE,MAAM,GAAG,MAAM,CAK9D"}
+{"version":3,"file":"prompt.d.ts","sourceRoot":"","sources":["../prompt.ts"],"names":[],"mappings":"AAIA,eAAO,MAAM,qBAAqB,uJAAuJ,CAAC;AAM1L,MAAM,WAAW,aAAa;IAC5B,KAAK,EAAE,MAAM,CAAC;IACd,WAAW,CAAC,EAAE,MAAM,CAAC;CACtB;AAED,MAAM,WAAW,cAAc;IAC7B,EAAE,EAAE,MAAM,CAAC;IACX,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,MAAM,CAAC;CACd;AAMD,wBAAgB,eAAe,CAC7B,KAAK,EAAE,MAAM,EACb,UAAU,EAAE,MAAM,EAAE,EACpB,cAAc,EAAE,aAAa,EAAE,EAC/B,eAAe,EAAE,cAAc,EAAE,GAChC,MAAM,CAyCR;AAED,eAAO,MAAM,yBAAyB,4CAA4C,CAAC;AAEnF,eAAO,MAAM,sBAAsB,sHAAsH,CAAC;AAE1J,wBAAgB,uBAAuB,CACrC,MAAM,EAAE,MAAM,EACd,SAAS,EAAE,MAAM,GAChB,MAAM,CAER;AAED,wBAAgB,yBAAyB,CACvC,SAAS,EAAE,MAAM,EACjB,KAAK,EAAE,MAAM,EAAE,GACd,MAAM,CAMR;AAMD,eAAO,MAAM,aAAa,q5BAuBzB,CAAC"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@spoons-and-mirrors/iam",
-  "version": "0.1.4",
+  "version": "0.1.6",
   "description": "Inter-agent messaging for OpenCode parallel subagents",
   "type": "module",
   "main": "dist/index.js",
@@ -29,12 +29,13 @@
   ],
   "license": "MIT",
   "peerDependencies": {
-    "@opencode-ai/plugin": ">=0.13.7"
+    "@opencode-ai/plugin": "^1.0.0"
   },
   "devDependencies": {
     "@opencode-ai/plugin": "^1.0.143",
     "@types/node": "^24.10.1",
     "bun-types": "^1.3.5",
+    "prettier": "^3.7.4",
     "typescript": "^5.9.3"
   }
 }