@spoons-and-mirrors/iam 0.1.0 → 0.1.2

package/README.md

@@ -1,40 +1,21 @@
 # IAM Plugin for OpenCode
 
-Inter-agent messaging for parallel subagents.
+Lets parallel subagents talk to each other. No configuration needed — just install and it works.
 
-## The `iam` Tool
+## What It Does
 
-| 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?"
-```
+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
+- Get **notified** when new messages arrive
 
 ## 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
+Agents get friendly names (agentA, agentB, ...) and automatically discover each other. When an agent has unread messages, they get an urgent notification.
 
-```
-iam/
-├── index.ts      # Plugin + tool + hooks
-├── prompt.ts     # LLM-facing prompts
-├── logger.ts     # Logs to .logs/iam.log
-├── PROGRESS.md   # Development history
-└── README.md
-```
+The system lives in memory — fast, no file clutter, resets on restart.
 
-## Logs
+## Debug Logs
 
-Debug logs written to `.logs/iam.log` (clears on restart). Shows all tool calls, messages sent, sessions registered, and notifications injected.
+For troubleshooting, check `.logs/iam.log` (clears on restart). Shows all tool calls, messages, and notifications.

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

package/dist/index.js

@@ -5,13 +5,14 @@ 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 session IDs of agents you can message
+- "sessions": Show agents you can message (e.g., agentA, agentB)
 - "read": Read all your messages (marks them as read)
-- "write": Send a message to another agent`;
+- "write": Send a message (requires 'to' and 'message' parameters)
+- "announce": Announce what you're working on (requires 'message' parameter)`;
 var ARG_DESCRIPTIONS = {
   action: "Action to perform",
-  to: "Recipient session ID (required for 'write')",
-  message: "Message content (required for 'write')"
+  to: "Recipient agent name, e.g. 'agentA' (required for 'write')",
+  message: "Message content (required for 'write'), or self-description (required for 'announce')"
 };
 var SESSIONS_EMPTY = `No other agents available yet.
 
@@ -19,18 +20,23 @@ 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(`
+  const lines = [`Agents you can message:
+`];
+  for (const agent of agents) {
+    if (agent.description) {
+      lines.push(`- ${agent.alias}: ${agent.description}`);
+    } else {
+      lines.push(`- ${agent.alias}`);
+    }
+  }
+  lines.push(``);
+  lines.push(`To send: use action="write" with to="<agent>" and message="..."`);
+  return lines.join(`
 `);
 }
-var READ_EMPTY = `No messages in your iam.`;
+var READ_EMPTY = `No messages in your IAM inbox.`;
 function readResult(messages, unreadCount) {
-  const lines = [`Your iam (${unreadCount} were unread):
+  const lines = [`Your IAM inbox (${unreadCount} were unread):
 `, `---`];
   for (const msg of messages) {
     const time = new Date(msg.timestamp).toISOString();
@@ -40,12 +46,35 @@ function readResult(messages, unreadCount) {
     lines.push(`---`);
   }
   lines.push(``);
-  lines.push(`To reply: iam write --to <sender_session_id> --message "..."`);
+  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}`];
+  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(``);
+    lines.push(`Use action="write" to coordinate with them if needed.`);
+  }
   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 writeUnknownRecipient(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) {
   return `Message sent!
 
@@ -58,21 +87,25 @@ function unknownAction(action) {
   return `Unknown action: ${action}`;
 }
 var SYSTEM_PROMPT = `
+<instructions tool="iam">
 # 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
+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
 
-Check your iam when notified about new messages.
+At the start of your task, use announce to let other agents know what you're doing.
+Check your inbox when notified about new messages.
+</instructions>
 `;
 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.
+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>`;
 }
 
@@ -116,6 +149,30 @@ var LOG = {
 // index.ts
 var inboxes = new Map;
 var activeSessions = new Set;
+var sessionToAlias = new Map;
+var aliasToSession = new Map;
+var agentDescriptions = new Map;
+var nextAgentIndex = 0;
+function getNextAlias() {
+  const letter = String.fromCharCode(65 + nextAgentIndex % 26);
+  const suffix = nextAgentIndex >= 26 ? Math.floor(nextAgentIndex / 26).toString() : "";
+  nextAgentIndex++;
+  return `agent${letter}${suffix}`;
+}
+function getAlias(sessionId) {
+  return sessionToAlias.get(sessionId) || sessionId;
+}
+function setDescription(sessionId, description) {
+  const alias = getAlias(sessionId);
+  agentDescriptions.set(alias, description);
+  log.info(LOG.SESSION, `Agent announced`, { alias, description });
+}
+function getDescription(alias) {
+  return agentDescriptions.get(alias);
+}
+function resolveAlias(aliasOrSessionId) {
+  return aliasToSession.get(aliasOrSessionId) || (activeSessions.has(aliasOrSessionId) ? aliasOrSessionId : undefined);
+}
 function generateId() {
   return Math.random().toString(36).substring(2, 10);
 }
@@ -156,7 +213,7 @@ function getKnownAgents(sessionId) {
   const agents = [];
   for (const id of activeSessions) {
     if (id !== sessionId) {
-      agents.push(id);
+      agents.push(getAlias(id));
     }
   }
   return agents;
@@ -164,7 +221,10 @@ function getKnownAgents(sessionId) {
 function registerSession(sessionId) {
   if (!activeSessions.has(sessionId)) {
     activeSessions.add(sessionId);
-    log.info(LOG.SESSION, `Session registered`, { sessionId, totalSessions: activeSessions.size });
+    const alias = getNextAlias();
+    sessionToAlias.set(sessionId, alias);
+    aliasToSession.set(alias, sessionId);
+    log.info(LOG.SESSION, `Session registered`, { sessionId, alias, totalSessions: activeSessions.size });
   }
 }
 var plugin = async () => {
@@ -174,7 +234,7 @@ var plugin = async () => {
       iam: tool({
         description: TOOL_DESCRIPTION,
         args: {
-          action: tool.schema.enum(["sessions", "read", "write"]).describe(ARG_DESCRIPTIONS.action),
+          action: tool.schema.enum(["sessions", "read", "write", "announce"]).describe(ARG_DESCRIPTIONS.action),
           to: tool.schema.string().optional().describe(ARG_DESCRIPTIONS.to),
           message: tool.schema.string().optional().describe(ARG_DESCRIPTIONS.message)
         },
@@ -189,7 +249,11 @@ var plugin = async () => {
               if (agents.length === 0) {
                 return SESSIONS_EMPTY;
               }
-              return sessionsResult(agents);
+              const agentsWithDesc = agents.map((alias) => ({
+                alias,
+                description: getDescription(alias)
+              }));
+              return sessionsResult(agentsWithDesc);
             }
             case "read": {
               const messages = getAllMessages(sessionId);
@@ -210,9 +274,28 @@ var plugin = async () => {
                 log.warn(LOG.TOOL, `write missing 'message'`, { sessionId });
                 return WRITE_MISSING_MESSAGE;
               }
-              const msg = sendMessage(sessionId, args.to, args.message);
+              const recipientSessionId = resolveAlias(args.to);
+              if (!recipientSessionId) {
+                log.warn(LOG.TOOL, `write unknown recipient`, { sessionId, to: args.to });
+                return writeUnknownRecipient(args.to, getKnownAgents(sessionId));
+              }
+              const senderAlias = getAlias(sessionId);
+              const msg = sendMessage(senderAlias, recipientSessionId, args.message);
               return writeResult(args.to, msg.id);
             }
+            case "announce": {
+              if (!args.message) {
+                log.warn(LOG.TOOL, `announce missing 'message'`, { sessionId });
+                return ANNOUNCE_MISSING_MESSAGE;
+              }
+              setDescription(sessionId, args.message);
+              const alias = getAlias(sessionId);
+              const parallelAgents = getKnownAgents(sessionId).map((agentAlias) => ({
+                alias: agentAlias,
+                description: getDescription(agentAlias)
+              }));
+              return announceResult(alias, parallelAgents);
+            }
             default:
               return unknownAction(args.action);
           }
@@ -268,7 +351,7 @@ var plugin = async () => {
     }
   };
 };
-var inbox_default = plugin;
+var iam_default = plugin;
 export {
-  inbox_default as default
+  iam_default as default
 };

package/dist/prompt.d.ts

@@ -1,22 +1,32 @@
-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 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 ARG_DESCRIPTIONS: {
     readonly action: "Action to perform";
-    readonly to: "Recipient session ID (required for 'write')";
-    readonly message: "Message content (required for 'write')";
+    readonly to: "Recipient agent name, e.g. 'agentA' (required for 'write')";
+    readonly message: "Message content (required for 'write'), or self-description (required for 'announce')";
 };
 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 sessionsResult(agents: {
+    alias: string;
+    description?: string;
+}[]): string;
+export declare const READ_EMPTY = "No messages in your IAM inbox.";
 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 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;
+}
+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 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 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 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,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"}
+{"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"}

package/package.json

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