@spoons-and-mirrors/iam 0.1.6 → 0.1.7

package/README.md

@@ -6,7 +6,7 @@ Enable parallel agents communication for opencode
 
 ## How It Works
 
-Parallel agents they can send messages to each other using the `broadcast` tool. Messages are relayed to the proper agent's context.
+Parallel agents can send messages to each other using the `broadcast` tool. Messages are relayed to the proper agent's context.
 
 ```mermaid
 sequenceDiagram
@@ -17,36 +17,42 @@ sequenceDiagram
     Parent->>A: spawn task
     Parent->>B: spawn task
 
-    Note over A,B: Both agents auto-register on first LLM call
+    Note over A,B: Registration
+
+    A->>A: broadcast(message="Doing X")
+    Note over A: Tool result shows agentB is available
+
+    B->>B: broadcast(message="Doing Y")
+    Note over B: Tool result shows agentA is available
 
     A->>B: broadcast(recipient="agentB", message="Question?")
 
-    Note over B: Receives message
-    Note over B: Responds
+    Note over B: Receives message in inbox
 
-    B->>A: broadcast(recipient="agentA", reply_to=[1], message="Answer!")
+    B->>A: broadcast(recipient="agentA", reply_to=1, message="Answer!")
+    Note over B: Tool result shows source message
 
     Note over A: Receives reply
-    Note over B: Tool output shows both reply and handled message
-    Note over B: Remove message from inbox
+    Note over B: Message removed from inbox
+    Note over B: Audit trace persists in tool result
 ```
 
 ## 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
+broadcast(message="...")                                  # Send to all agents
+broadcast(recipient="agentB", message="...")              # Send to specific agent
+broadcast(reply_to=1, message="...")                      # Mark message 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]`) |
+| Parameter   | Required | Description                               |
+| ----------- | -------- | ----------------------------------------- |
+| `message`   | Yes      | Your message content                      |
+| `recipient` | No       | Target agent(s), comma-separated          |
+| `reply_to`  | No       | Message ID to mark as handled (e.g., `1`) |
 
 ## Receiving Messages
 
@@ -55,17 +61,16 @@ 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"]
+    {"id": 1, "from": "agentA", "body": "What's the status on the API?"},
+    {"id": 2, "from": "agentA", "body": "Also, can you check the tests?"}
+  ]
 }
 ```
 
-The `agents` array always shows available agents to message. This is injected even when there are no incoming messages.
-
 Messages persist in the inbox until the agent marks them as handled using `reply_to`.
 
+**Discovery:** Agents discover each other by calling `broadcast` - the tool result shows all available agents.
+
 ## Installation
 
 Add to your OpenCode config:
@@ -80,21 +85,19 @@ Add to your OpenCode config:
 # Parent spawns two agents to work on different parts of a feature
 
 AgentA (working on frontend):
-  → broadcast(message="Starting frontend work")
-  → ... does work ...
-  → broadcast(recipient="agentB", message="Need the API schema")
+  -> broadcast(message="Starting frontend work")
+     # Tool result shows: "Available agents: agentB"
+  -> ... does work ...
+  -> broadcast(recipient="agentB", message="Need the API schema")
 
 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: {...}")
+  -> broadcast(message="Starting backend work")
+     # Tool result shows: "Available agents: agentA"
+  -> ... sees AgentA's question in inbox ...
+  -> broadcast(recipient="agentA", reply_to=1, message="Here's the schema: {...}")
+     # Tool result shows: Marked as handled: #1 from agentA
 
 AgentA:
-  → ... sees AgentB's response in inbox ...
-  → broadcast(reply_to=[1], message="Got it, thanks!")
+  -> ... 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,CAAC;AAijBlD,QAAA,MAAM,MAAM,EAAE,MAwTb,CAAC;AAEF,eAAe,MAAM,CAAC"}
+{"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,MA0Tb,CAAC;AAEF,eAAe,MAAM,CAAC"}

package/dist/index.js

@@ -3,7 +3,7 @@ import { tool } from "@opencode-ai/plugin";
 
 // prompt.ts
 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) {
+function broadcastResult(alias, recipients, parallelAgents, handledMessage) {
   const lines = [];
   lines.push(`You are: ${alias}`);
   lines.push(``);
@@ -24,13 +24,11 @@ function broadcastResult(alias, recipients, parallelAgents, handledMessages) {
     const recipientStr = recipients.length === 1 ? recipients[0] : recipients.join(", ");
     lines.push(`Message sent to: ${recipientStr}`);
   }
-  if (handledMessages.length > 0) {
+  if (handledMessage) {
     lines.push(``);
-    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}"`);
-    }
+    const preview = handledMessage.body.length > 80 ? handledMessage.body.substring(0, 80) + "..." : handledMessage.body;
+    lines.push(`Marked as handled: #${handledMessage.id} from ${handledMessage.from}`);
+    lines.push(`  "${preview}"`);
   }
   return lines.join(`
 `);
@@ -63,9 +61,8 @@ 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="...")\`
+Use \`reply_to\` to mark a message as handled (they persist until you do):
+- \`broadcast(recipient="agentA", reply_to=1, message="...")\`
 </instructions>
 `;
 
@@ -430,7 +427,7 @@ var plugin = async (ctx) => {
         args: {
           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])")
+          reply_to: tool.schema.number().optional().describe("Message ID to mark as handled")
         },
         async execute(args, context) {
           const sessionId = context.sessionID;
@@ -459,14 +456,16 @@ var plugin = async (ctx) => {
             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
-            });
+          let handledMessage;
+          if (args.reply_to !== undefined) {
+            const handled = markMessagesAsHandled(sessionId, [args.reply_to]);
+            if (handled.length > 0) {
+              handledMessage = handled[0];
+              log.info(LOG.TOOL, `Handled message via reply_to`, {
+                alias,
+                msgId: args.reply_to
+              });
+            }
           }
           const knownAgents = getKnownAliases(sessionId);
           const parallelAgents = getParallelAgents(sessionId);
@@ -480,7 +479,7 @@ var plugin = async (ctx) => {
             log.info(LOG.TOOL, `No recipients, returning agent info`, {
               alias
             });
-            return broadcastResult(alias, [], parallelAgents, handledMessages);
+            return broadcastResult(alias, [], parallelAgents, handledMessage);
           }
           const parentId = await getParentId(client, sessionId);
           const recipientSessions = [];
@@ -511,7 +510,7 @@ var plugin = async (ctx) => {
             log.info(LOG.TOOL, `No valid recipients after filtering`, {
               alias
             });
-            return broadcastResult(alias, [], parallelAgents, handledMessages);
+            return broadcastResult(alias, [], parallelAgents, handledMessage);
           }
           const isTargetingParent = parentId && recipientSessions.includes(parentId);
           for (const recipientSessionId of recipientSessions) {
@@ -539,7 +538,7 @@ var plugin = async (ctx) => {
               });
             }
           }
-          return broadcastResult(alias, validTargets, parallelAgents, handledMessages);
+          return broadcastResult(alias, validTargets, parallelAgents, handledMessage);
         }
       })
     },

package/dist/prompt.d.ts

@@ -8,10 +8,10 @@ export interface HandledMessage {
     from: string;
     body: string;
 }
-export declare function broadcastResult(alias: string, recipients: string[], parallelAgents: ParallelAgent[], handledMessages: HandledMessage[]): string;
+export declare function broadcastResult(alias: string, recipients: string[], parallelAgents: ParallelAgent[], handledMessage?: 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";
+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 a message as handled (they persist until you do):\n- `broadcast(recipient=\"agentA\", reply_to=1, 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,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"}
+{"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,cAAc,CAAC,EAAE,cAAc,GAC9B,MAAM,CA2CR;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,00BAsBzB,CAAC"}

package/package.json

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