@bastani/atomic 0.9.16-alpha.9 → 0.9.16

package/dist/builtin/intercom/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bastani/intercom",
-  "version": "0.9.16-alpha.9",
+  "version": "0.9.16",
   "private": true,
   "description": "Atomic extension providing a private coordination channel between parent and child agent sessions. Fork of: https://github.com/nicobailon/pi-intercom",
   "contributors": [
@@ -44,7 +44,7 @@
   },
   "peerDependencies": {
     "@bastani/atomic": "*",
-    "@earendil-works/pi-tui": "^0.84.3"
+    "@earendil-works/pi-tui": "^0.84.4"
   },
   "peerDependenciesMeta": {
     "@bastani/atomic": {

package/dist/builtin/intercom/skills/intercom/SKILL.md

@@ -81,6 +81,8 @@ Live sessions accept an exact full session ID or exact case-insensitive name. Or
 
 Send material updates through Intercom to every affected workflow stage, including stages that have not started. Atomic queues messages for known pending stages and delivers them when their sessions initialize:
 
+Before steering a stage, join its invocation group. Use the Intercom `groups` action to discover it. Workflow invocation groups are named `workflow:<rootRunId>`.
+
 ```typescript
 intercom({
   action: "send",
@@ -94,18 +96,21 @@ The stage receives the ordinary inbound Intercom message before its first model
 
 ### Runtime named groups
 
-Plain chat sessions can create or join a group without restarting:
+Plain chat sessions can add and remove group memberships without restarting:
 
 ```typescript
-// Join or create the named group. Both sessions should run this call.
+// Add a membership. Existing memberships remain active.
 intercom({ action: "join", group: "api-review" })
-intercom({ action: "list" }) // now shows only peers in api-review
 
-// Leave the named group and return to the resolved startup home group.
+// Discover every available group and see membership markers.
+intercom({ action: "groups" })
+
+// Remove one membership, or reset to home by omitting group.
+intercom({ action: "leave", group: "api-review" })
 intercom({ action: "leave" })
 ```
 
-Joining changes broker presence without changing the session ID. `default` is the shared group. The names `true` and `auto` are reserved for subagent auto-groups and are rejected. Subagents launched after a join inherit the joined group. Ordinary `send`/`ask` calls remain group-isolated; only an authorized `contact_supervisor` call can cross groups.
+`list` still lists sessions: without a filter it returns every peer sharing at least one membership. `default` remains shared, while `true` and `auto` remain reserved. Later subagents inherit the most recently joined membership. Ordinary `send`/`ask` requires a shared membership; only authorized `contact_supervisor` traffic crosses group boundaries.
 
 ### Pattern 3: Reply Naturally
 
@@ -243,14 +248,15 @@ In Atomic workflows, each invocation has its own Intercom group, and parallel st
 
 | Action | Behavior | Use When |
 |--------|----------|----------|
-| `join` | Joins or creates a named group in place | Two plain chat sessions need a private group |
-| `leave` | Returns to the resolved home group | Restore the session's startup group |
+| `join` | Adds or creates a named membership in place | Sessions need another shared routing group |
+| `leave` | Removes one named membership, or resets to home when omitted | Stop sharing one group or restore startup membership |
+| `groups` | Lists every available group with counts and membership markers | Discover a group instead of guessing its name |
 | `send` | Fire-and-forget to a live session, or durable `queued` delivery to `<runId>:<stageKey>` before a workflow stage starts | You don't need a response |
 | `ask` | Blocks until a live recipient replies (10 min timeout); refused for an unstarted stage | You need an answer to continue |
 | `reply` | Responds to the active or pending inbound ask; `to` accepts an exact full session ID or exact session name | You were asked something and need to answer naturally |
 | `pending` | Lists unresolved inbound asks | You need to see who is waiting before replying |
-| `list` | Returns all sessions in the current group with full session IDs and live status | You need to discover targets or choose an idle peer |
-| `status` | Returns your connection state and current group | Troubleshooting |
+| `list` | Returns all sessions sharing any membership, with full IDs and live status | Discover targets or choose an idle peer |
+| `status` | Returns connection state and every current membership | Troubleshooting |
 
 Inside workflows, `ask` may target a sibling stage that has already completed. If that stage retains a valid conversation, Atomic automatically schedules a post-mortem turn there and preserves the exact child-to-child reply thread; do not send a separate workflow follow-up. Missing, deleted, non-resumable, or failed-to-reopen completed targets return an actionable error. A parent or unrelated session cannot satisfy the pending ask.
 
@@ -471,7 +477,7 @@ if (!result.delivered) {
 
 ### Session not appearing in list
 
-1. Check intercom is enabled: `intercom({ action: "status" })`
+1. Check Intercom connection status: `intercom({ action: "status" })`
 2. Verify the target session has loaded pi-intercom
 3. Ensure both sessions are on the same machine (intercom is same-machine only)
 

package/dist/builtin/intercom/types.ts

@@ -7,10 +7,18 @@ export interface SessionInfo {
   startedAt: number;
   lastActivity: number;
   status?: string;
-  /** Session's intercom group; undefined is treated as the shared "default" group. */
+  /** Session's normalized intercom group memberships. */
+  groups?: string[];
+  /** Legacy single-group membership; accepted alongside `groups` for compatibility. */
   group?: string;
 }
 
+export interface GroupSummary {
+	group: string;
+	sessionCount: number;
+	member: boolean;
+}
+
 export interface Message {
   id: string;
   timestamp: number;
@@ -53,6 +61,9 @@ export type ClientMessage =
 	  }
 	| { type: "unregister" }
   | { type: "list"; requestId: string; group?: string }
+	| { type: "list_groups"; requestId: string }
+	| { type: "join_group"; requestId: string; group: string }
+	| { type: "leave_group"; requestId: string; group?: string }
   | { type: "authorize_supervisor"; requestId: string; childName: string; capability?: string }
   | { type: "send" | "supervisor_send"; to: string; message: Message; attemptId?: string }
 	| {
@@ -82,12 +93,23 @@ export type ClientMessage =
 		reason?: string;
 		reasonCode?: "message_id_conflict";
 	  }
-  | { type: "presence"; name?: string; status?: string; model?: string; group?: string; requestId?: string };
+  | {
+      type: "presence";
+      name?: string;
+      status?: string;
+      model?: string;
+      groups?: string[];
+      /** Legacy single-group membership; accepted alongside `groups` for compatibility. */
+      group?: string;
+      requestId?: string;
+    };
 
 export type BrokerMessage =
   | { type: "registered"; sessionId: string; supervisorSessionId?: string }
   | { type: "registration_failed"; reason: string }
   | { type: "sessions"; requestId: string; sessions: SessionInfo[] }
+	| { type: "groups"; requestId: string; groups: GroupSummary[] }
+	| { type: "membership_ack"; requestId: string; groups: string[] }
   | { type: "supervisor_authorized"; requestId: string; capability: string; supervisorSessionId: string; childName: string }
   | { type: "message"; from: SessionInfo; message: Message; channel?: "supervisor" }
 	| { type: "pending_stage_notification"; requestId: string; from: SessionInfo; message: Message }