@spoons-and-mirrors/iam 0.1.2 → 0.1.3

package/README.md

@@ -5,17 +5,42 @@ Lets parallel subagents talk to each other. No configuration needed — just ins
 ## What It Does
 
 When you spawn multiple agents with the `task` tool, they can:
-- **Announce** what they're working on
-- **Discover** other agents and see what they're doing
-- **Message** each other to coordinate work
+- **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
 
 ## How It Works
 
-Agents get friendly names (agentA, agentB, ...) and automatically discover each other. When an agent has unread messages, they get an urgent notification.
+Agents get friendly names (agentA, agentB, ...) and automatically discover each other.
 
-The system lives in memory — fast, no file clutter, resets on restart.
+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.
+
+Agents who haven't announced are told they MUST announce before continuing.
+
+When an agent completes their task, they're encouraged to broadcast a completion message so others know.
+
+## Actions
+
+| 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. |
+
+## Examples
+
+```
+# Announce what you're doing (also shows parallel agents)
+action="announce", message="Refactoring the auth module"
+
+# Message everyone
+action="broadcast", message="Found a bug in config.ts, heads up"
+
+# 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"
+```
 
 ## Debug Logs
 
-For troubleshooting, check `.logs/iam.log` (clears on restart). Shows all tool calls, messages, and notifications.
+For troubleshooting, check `.logs/iam.log` (clears on restart).

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;AAkJjD,QAAA,MAAM,MAAM,EAAE,MAyKb,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,CAAA;AAwJjD,QAAA,MAAM,MAAM,EAAE,MAoKb,CAAA;AAED,eAAe,MAAM,CAAA"}

package/dist/index.js

@@ -5,86 +5,83 @@ import { tool } from "@opencode-ai/plugin";
 var TOOL_DESCRIPTION = `Inter-agent messaging. Use this to communicate with other parallel agents (task tools).
 
 Actions:
-- "sessions": Show agents you can message (e.g., agentA, agentB)
-- "read": Read all your messages (marks them as read)
-- "write": Send a message (requires 'to' and 'message' parameters)
-- "announce": Announce what you're working on (requires 'message' parameter)`;
+- "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 agent name, e.g. 'agentA' (required for 'write')",
-  message: "Message content (required for 'write'), or self-description (required for 'announce')"
+  to: "Recipient(s): 'agentA', 'agentA,agentC', or 'all' (default: all)",
+  message: "Your announcement or message content"
 };
-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) {
-  const lines = [`Agents you can message:
-`];
+function formatAgentList(agents) {
+  const lines = [];
   for (const agent of agents) {
     if (agent.description) {
-      lines.push(`- ${agent.alias}: ${agent.description}`);
+      lines.push(`• ${agent.alias} is working on: ${agent.description}`);
     } else {
-      lines.push(`- ${agent.alias}`);
+      lines.push(`• ${agent.alias} is running (hasn't announced yet)`);
     }
   }
-  lines.push(``);
-  lines.push(`To send: use action="write" with to="<agent>" and message="..."`);
-  return lines.join(`
-`);
+  return lines;
 }
-var READ_EMPTY = `No messages in your IAM inbox.`;
-function readResult(messages, unreadCount) {
-  const lines = [`Your IAM 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(`---`);
+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="..."`);
+  }
+  if (!hasAnnounced) {
+    lines.push(``);
+    lines.push(`IMPORTANT: You MUST use action="announce" to declare what you're working on before continuing.`);
   }
-  lines.push(``);
-  lines.push(`To reply: use action="write" with to="<sender>" and message="..."`);
   return lines.join(`
 `);
 }
-var WRITE_MISSING_TO = `Error: 'to' parameter is required for action="write".`;
-var WRITE_MISSING_MESSAGE = `Error: 'message' parameter is required for action="write".`;
-var ANNOUNCE_MISSING_MESSAGE = `Error: 'message' parameter is required for action="announce". Describe what you're working on.`;
 function announceResult(alias, parallelAgents) {
-  const lines = [`Announced! Other agents will see your description when they list sessions.`, ``, `You are: ${alias}`];
+  const lines = [
+    `Announced! Other agents will see your description when they call announce.`,
+    ``,
+    `You are: ${alias}`
+  ];
   if (parallelAgents.length > 0) {
     lines.push(``);
     lines.push(`--- Parallel Agents ---`);
-    for (const agent of parallelAgents) {
-      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(...formatAgentList(parallelAgents));
     lines.push(``);
-    lines.push(`Use action="write" to coordinate with them if needed.`);
+    lines.push(`Use action="broadcast" to coordinate with them.`);
+  } else {
+    lines.push(``);
+    lines.push(`No other agents running yet.`);
   }
   return lines.join(`
 `);
 }
-function writeUnknownRecipient(to, known) {
+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 writeResult(to, messageId) {
+function broadcastResult(recipients, messageId) {
+  const recipientStr = recipients.length === 1 ? recipients[0] : recipients.join(", ");
   return `Message sent!
 
-To: ${to}
+To: ${recipientStr}
 Message ID: ${messageId}
 
-The recipient will be notified.`;
+Recipients will be notified.`;
 }
 function unknownAction(action) {
-  return `Unknown action: ${action}`;
+  return `Unknown action: ${action}. Valid actions: announce, read, broadcast`;
 }
 var SYSTEM_PROMPT = `
 <instructions tool="iam">
@@ -94,12 +91,15 @@ You have access to an \`iam\` tool for communicating with other parallel agents.
 
 Usage:
 - action="announce", message="..." - Announce what you're working on (do this first!)
-- action="sessions" - See other agents and what they're working on
 - action="read" - Read your messages
-- action="write", to="agentA", message="..." - Send a message
+- action="broadcast", message="..." - Message all agents
+- action="broadcast", to="agentA", message="..." - Message specific agent(s)
 
 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.
+
+When you complete your task, broadcast to all: "Done. Here's what I found/did: ..."
 </instructions>
 `;
 function urgentNotification(unreadCount) {
@@ -170,6 +170,10 @@ function setDescription(sessionId, description) {
 function getDescription(alias) {
   return agentDescriptions.get(alias);
 }
+function hasAnnounced(sessionId) {
+  const alias = getAlias(sessionId);
+  return agentDescriptions.has(alias);
+}
 function resolveAlias(aliasOrSessionId) {
   return aliasToSession.get(aliasOrSessionId) || (activeSessions.has(aliasOrSessionId) ? aliasOrSessionId : undefined);
 }
@@ -218,6 +222,12 @@ function getKnownAgents(sessionId) {
   }
   return agents;
 }
+function getParallelAgents(sessionId) {
+  return getKnownAgents(sessionId).map((alias) => ({
+    alias,
+    description: getDescription(alias)
+  }));
+}
 function registerSession(sessionId) {
   if (!activeSessions.has(sessionId)) {
     activeSessions.add(sessionId);
@@ -234,66 +244,62 @@ var plugin = async () => {
       iam: tool({
         description: TOOL_DESCRIPTION,
         args: {
-          action: tool.schema.enum(["sessions", "read", "write", "announce"]).describe(ARG_DESCRIPTIONS.action),
+          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)
         },
         async execute(args, context) {
           const sessionId = context.sessionID;
           registerSession(sessionId);
-          log.debug(LOG.TOOL, `iam action: ${args.action}`, { sessionId, args });
+          const alias = getAlias(sessionId);
+          const announced = hasAnnounced(sessionId);
+          log.debug(LOG.TOOL, `iam action: ${args.action}`, { sessionId, alias, 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;
-              }
-              const agentsWithDesc = agents.map((alias) => ({
-                alias,
-                description: getDescription(alias)
-              }));
-              return sessionsResult(agentsWithDesc);
-            }
             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 });
+              log.debug(LOG.TOOL, `read inbox`, { alias, total: messages.length, unread: unreadCount });
               markAllRead(sessionId);
-              if (messages.length === 0) {
-                return READ_EMPTY;
-              }
-              return readResult(messages, unreadCount);
+              return readResult(alias, messages, unreadCount, announced);
             }
-            case "write": {
-              if (!args.to) {
-                log.warn(LOG.TOOL, `write missing 'to'`, { sessionId });
-                return WRITE_MISSING_TO;
-              }
+            case "broadcast": {
               if (!args.message) {
-                log.warn(LOG.TOOL, `write missing 'message'`, { sessionId });
-                return WRITE_MISSING_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 (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);
               }
-              const recipientSessionId = resolveAlias(args.to);
-              if (!recipientSessionId) {
-                log.warn(LOG.TOOL, `write unknown recipient`, { sessionId, to: args.to });
-                return writeUnknownRecipient(args.to, getKnownAgents(sessionId));
+              let messageId = "";
+              for (const recipientSessionId of recipientSessions) {
+                const msg = sendMessage(alias, recipientSessionId, args.message);
+                messageId = msg.id;
               }
-              const senderAlias = getAlias(sessionId);
-              const msg = sendMessage(senderAlias, recipientSessionId, args.message);
-              return writeResult(args.to, msg.id);
+              return broadcastResult(targetAliases, messageId);
             }
             case "announce": {
               if (!args.message) {
-                log.warn(LOG.TOOL, `announce missing 'message'`, { sessionId });
-                return ANNOUNCE_MISSING_MESSAGE;
+                log.warn(LOG.TOOL, `announce missing 'message'`, { alias });
+                return `Error: 'message' parameter is required for action="announce". Describe what you're working on.`;
               }
               setDescription(sessionId, args.message);
-              const alias = getAlias(sessionId);
-              const parallelAgents = getKnownAgents(sessionId).map((agentAlias) => ({
-                alias: agentAlias,
-                description: getDescription(agentAlias)
-              }));
+              const parallelAgents = getParallelAgents(sessionId);
               return announceResult(alias, parallelAgents);
             }
             default:

package/dist/prompt.d.ts

@@ -1,32 +1,25 @@
-export declare const TOOL_DESCRIPTION = "Inter-agent messaging. Use this to communicate with other parallel agents (task tools).\n\nActions:\n- \"sessions\": Show agents you can message (e.g., agentA, agentB)\n- \"read\": Read all your messages (marks them as read)\n- \"write\": Send a message (requires 'to' and 'message' parameters)\n- \"announce\": Announce what you're working on (requires 'message' parameter)";
+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 agent name, e.g. 'agentA' (required for 'write')";
-    readonly message: "Message content (required for 'write'), or self-description (required for 'announce')";
+    readonly to: "Recipient(s): 'agentA', 'agentA,agentC', or 'all' (default: all)";
+    readonly message: "Your announcement or message content";
 };
-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: {
+export interface ParallelAgent {
     alias: string;
     description?: string;
-}[]): string;
-export declare const READ_EMPTY = "No messages in your IAM inbox.";
-export declare function readResult(messages: {
+}
+export declare function formatAgentList(agents: ParallelAgent[]): string[];
+export declare function readResult(alias: string, messages: {
     from: string;
     body: string;
     timestamp: number;
     read: boolean;
-}[], unreadCount: number): string;
-export declare const WRITE_MISSING_TO = "Error: 'to' parameter is required for action=\"write\".";
-export declare const WRITE_MISSING_MESSAGE = "Error: 'message' parameter is required for action=\"write\".";
-export declare const ANNOUNCE_MISSING_MESSAGE = "Error: 'message' parameter is required for action=\"announce\". Describe what you're working on.";
-export interface ParallelAgent {
-    alias: string;
-    description?: string;
-}
+}[], unreadCount: number, hasAnnounced: boolean): string;
 export declare function announceResult(alias: string, parallelAgents: ParallelAgent[]): string;
-export declare function writeUnknownRecipient(to: string, known: string[]): string;
-export declare function writeResult(to: string, messageId: string): 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=\"sessions\" - See other agents and what they're working on\n- action=\"read\" - Read your messages\n- action=\"write\", to=\"agentA\", message=\"...\" - Send a message\n\nAt the start of your task, use announce to let other agents know what you're doing.\nCheck your inbox when notified about new messages.\n</instructions>\n";
+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;
 //# 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,2XAMgD,CAAC;AAE9E,eAAO,MAAM,gBAAgB;;;;CAInB,CAAC;AAMX,eAAO,MAAM,cAAc,0JAIS,CAAC;AAErC,wBAAgB,cAAc,CAAC,MAAM,EAAE;IAAC,KAAK,EAAE,MAAM,CAAC;IAAC,WAAW,CAAC,EAAE,MAAM,CAAA;CAAC,EAAE,GAAG,MAAM,CAYtF;AAED,eAAO,MAAM,UAAU,mCAAmC,CAAC;AAE3D,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,CAiBR;AAED,eAAO,MAAM,gBAAgB,4DAA0D,CAAC;AACxF,eAAO,MAAM,qBAAqB,iEAA+D,CAAC;AAClG,eAAO,MAAM,wBAAwB,qGAAmG,CAAC;AAEzI,MAAM,WAAW,aAAa;IAC5B,KAAK,EAAE,MAAM,CAAC;IACd,WAAW,CAAC,EAAE,MAAM,CAAC;CACtB;AAED,wBAAgB,cAAc,CAAC,KAAK,EAAE,MAAM,EAAE,cAAc,EAAE,aAAa,EAAE,GAAG,MAAM,CAkBrF;AAED,wBAAgB,qBAAqB,CAAC,EAAE,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,EAAE,GAAG,MAAM,CAMzE;AAED,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,mkBAezB,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,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"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@spoons-and-mirrors/iam",
-  "version": "0.1.2",
+  "version": "0.1.3",
   "description": "Inter-agent messaging for OpenCode parallel subagents",
   "type": "module",
   "main": "dist/index.js",