@bastani/atomic 0.9.16-alpha.7 → 0.9.16-alpha.9

package/dist/builtin/intercom/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bastani/intercom",
-  "version": "0.9.16-alpha.7",
+  "version": "0.9.16-alpha.9",
   "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": [

package/dist/builtin/intercom/session-target.ts

@@ -0,0 +1,54 @@
+import type { SessionInfo } from "./types.js";
+
+export type SessionTargetResolution =
+  | { kind: "resolved"; session: SessionInfo }
+  | { kind: "ambiguous_name"; matches: readonly SessionInfo[] }
+  | { kind: "not_found" };
+
+/** Resolve an Intercom session by exact ID or exact case-insensitive name. */
+export function resolveSessionTarget(
+  sessions: readonly SessionInfo[],
+  nameOrId: string,
+): SessionTargetResolution {
+  const target = nameOrId.trim();
+  const exactId = sessions.find((session) => session.id === target);
+  if (exactId !== undefined) return { kind: "resolved", session: exactId };
+
+  const lowerTarget = target.toLowerCase();
+  const exactNames = sessions.filter(
+    (session) => session.name?.toLowerCase() === lowerTarget,
+  );
+  if (exactNames.length === 1) {
+    return { kind: "resolved", session: exactNames[0]! };
+  }
+  if (exactNames.length > 1) {
+    return { kind: "ambiguous_name", matches: exactNames };
+  }
+
+  return { kind: "not_found" };
+}
+
+export function sessionTargetFailureReason(
+  target: string,
+  resolution: Exclude<SessionTargetResolution, { kind: "resolved" }>,
+): string {
+  if (resolution.kind === "ambiguous_name") {
+    return `Multiple sessions named "${target}" are connected. Use the session ID instead.`;
+  }
+  return "Session not found";
+}
+
+export interface SessionListingClient {
+  listSessions(): Promise<SessionInfo[]>;
+}
+
+/** Resolve a target through the broker's current session list. */
+export async function resolveSessionTargetId(
+  client: SessionListingClient,
+  nameOrId: string,
+): Promise<string | null> {
+  const resolution = resolveSessionTarget(await client.listSessions(), nameOrId);
+  if (resolution.kind === "resolved") return resolution.session.id;
+  if (resolution.kind === "not_found") return null;
+  throw new Error(sessionTargetFailureReason(nameOrId, resolution));
+}

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

@@ -75,7 +75,22 @@ intercom({ action: "list" })
 intercom({ action: "ask", to: "6332faab-1111-4222-8333-123456789abc", message: "Which option should I use?" })
 ```
 
-Intercom accepts only an exact full session ID or an exact case-insensitive session name. Use the full ID printed by `list` or the session's exact name.
+Live sessions accept an exact full session ID or exact case-insensitive name. Ordinary `send` to a known workflow stage whose session has not initialized uses the exact `<runId>:<stageKey>` identity. Unknown runs and stages retain the ordinary unknown-target failure.
+
+### Deliver to workflow stages that have not started
+
+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:
+
+```typescript
+intercom({
+  action: "send",
+  to: "<runId>:reviewer",
+  message: "Scope changed: preserve raw amendment text in the verification oracle."
+})
+// → queued, distinct from live-session delivered, with the FIFO position
+```
+
+The stage receives the ordinary inbound Intercom message before its first model turn under **Messages received before you started**, with real sender identity and a `Sent:` timestamp. Only same-workflow-group sessions may queue messages. Each exact run/stage key holds at most 50 queued messages; the next send is refused rather than evicting one. Resume/replay, broker restart, and stage-attempt restart preserve exactly-once delivery. If the stage is skipped, cancelled, or becomes terminal before its session initializes, the message becomes undeliverable and acknowledgment-requesting senders receive a correlated failure. Do not use `ask`: Atomic returns `pending_stage_ask_unsupported` and recommends ordinary `send` instead of holding an unbounded waiter.
 
 ### Runtime named groups
 
@@ -230,8 +245,8 @@ In Atomic workflows, each invocation has its own Intercom group, and parallel st
 |--------|----------|----------|
 | `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 |
-| `send` | Fire-and-forget | You don't need a response |
-| `ask` | Blocks until reply (10 min timeout) | You need an answer to continue |
+| `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 |

package/dist/builtin/intercom/source-ownership.ts

@@ -0,0 +1,31 @@
+import { type SubagentChildPolicy } from "@bastani/atomic";
+import type { Message } from "./types.js";
+
+export function buildSubagentMessageSource(
+  runIdValue: string | undefined,
+  agentValue: string | undefined,
+  indexValue: string | undefined,
+): Message["source"] | undefined {
+  const subagentRunId = runIdValue?.trim();
+  if (!subagentRunId) return undefined;
+  const subagentAgent = agentValue?.trim();
+  const rawIndex = indexValue?.trim();
+  const parsedIndex = rawIndex === undefined ? undefined : Number(rawIndex);
+  const subagentIndex = parsedIndex !== undefined && Number.isInteger(parsedIndex) && parsedIndex >= 0
+    ? parsedIndex : undefined;
+  return {
+    subagentRunId,
+    ...(subagentAgent ? { subagentAgent } : {}),
+    ...(subagentIndex !== undefined ? { subagentIndex } : {}),
+  };
+}
+
+export function readSubagentMessageSource(policy?: SubagentChildPolicy): Message["source"] | undefined {
+	const identity = policy?.intercom;
+	if (!identity) return undefined;
+	return {
+		subagentRunId: identity.runId,
+		subagentAgent: identity.agent,
+		subagentIndex: identity.index,
+	};
+}

package/dist/builtin/intercom/types.ts

@@ -0,0 +1,115 @@
+export interface SessionInfo {
+  id: string;
+  name?: string;
+  cwd: string;
+  model: string;
+  pid: number;
+  startedAt: number;
+  lastActivity: number;
+  status?: string;
+  /** Session's intercom group; undefined is treated as the shared "default" group. */
+  group?: string;
+}
+
+export interface Message {
+  id: string;
+  timestamp: number;
+  replyTo?: string;
+  expectsReply?: boolean;
+  /** Actionable remote failure for a correlated ask reply. */
+  replyError?: string;
+  source?: {
+    subagentRunId: string;
+    subagentAgent?: string;
+    subagentIndex?: number;
+  };
+  content: {
+    text: string;
+    attachments?: Attachment[];
+  };
+}
+
+export interface Attachment {
+  type: "file" | "snippet" | "context";
+  name: string;
+  content: string;
+  language?: string;
+}
+/** Broker capability metadata binding a child registration to its supervisor. */
+export interface SupervisorRegistration {
+  capability: string;
+  supervisorSessionId: string;
+}
+
+
+export type ClientMessage =
+	| {
+			type: "register";
+			session: Omit<SessionInfo, "id">;
+			/** Internal host-owned identity retained across broker reconnects. */
+			returnAddress?: string;
+			supervisor?: SupervisorRegistration;
+			supervisorOwnerToken?: string;
+	  }
+	| { type: "unregister" }
+  | { type: "list"; requestId: string; group?: string }
+  | { type: "authorize_supervisor"; requestId: string; childName: string; capability?: string }
+  | { type: "send" | "supervisor_send"; to: string; message: Message; attemptId?: string }
+	| {
+			type: "send_pending_stage_notification";
+			runId: string;
+			capability: string;
+			to: string;
+			senderRegistrationName?: string;
+			senderReturnAddress?: string;
+			message: Message;
+			attemptId?: string;
+	  }
+	| { type: "pending_stage_notification_result"; requestId: string; delivered: boolean }
+  | { type: "register_pending_stage_route"; runId: string; group: string; capability: string }
+  | {
+      type: "register_live_workflow_stage_route";
+      requestId: string;
+      runId: string;
+      stageKeys: string[];
+      capability: string;
+    }
+	| {
+		type: "pending_stage_message_result";
+		requestId: string;
+		outcome: "queued" | "delivered" | "forward" | "refused";
+		position?: number;
+		reason?: string;
+		reasonCode?: "message_id_conflict";
+	  }
+  | { type: "presence"; name?: string; status?: string; model?: string; 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: "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 }
+	| {
+			type: "pending_stage_message";
+			requestId: string;
+			from: SessionInfo;
+			senderRegistrationName?: string;
+			senderReturnAddress?: string;
+			runId: string;
+			stageKey: string;
+			message: Message;
+			live?: boolean;
+	  }
+  | { type: "live_workflow_stage_route_registered"; requestId: string }
+  | { type: "presence_update"; session: SessionInfo }
+  | { type: "session_joined"; session: SessionInfo }
+  | { type: "session_left"; sessionId: string }
+  | { type: "peer_disconnected"; replyTo: string; peerSessionId: string; peerName?: string }
+  | { type: "presence_ack"; requestId: string; group: string }
+  | { type: "presence_failed"; requestId: string; reason: string }
+  | { type: "error"; error: string }
+  | { type: "delivered"; messageId: string; attemptId?: string }
+  | { type: "queued"; messageId: string; attemptId?: string; runId: string; stageKey: string; position: number }
+	| { type: "delivery_failed"; messageId: string; reason: string; reasonCode?: "message_id_conflict"; attemptId?: string };