@bastani/atomic 0.9.16-alpha.2 → 0.9.16-alpha.3

package/dist/builtin/intercom/intercom-tool.ts

@@ -1,602 +0,0 @@
-import type { ExtensionAPI } from "@bastani/atomic";
-import { randomUUID } from "crypto";
-import { Type } from "typebox";
-import { Text } from "@earendil-works/pi-tui";
-import type { IntercomClient } from "./broker/client.js";
-import { requestParentAskHandoff } from "./parent-ask-handoff.js";
-import type { ReplyWait, ReplyWaitAdmission } from "./reply-waiter.ts";
-import { renderIntercomResult } from "./result-renderers.js";
-import {
-  type ChildOrchestratorMetadata,
-  formatAttachments,
-  formatSessionListRow,
-  getErrorMessage,
-  previewText,
-  toError,
-} from "./intercom-utils.js";
-import type { ReplyTracker } from "./reply-tracker.js";
-import { resolveSessionTargetId } from "./session-target.js";
-import { normalizeGroup, validateRuntimeGroup } from "./group.js";
-
-interface IntercomToolDeps {
-  childOrchestratorMetadata?: ChildOrchestratorMetadata | null | (() => ChildOrchestratorMetadata | null);
-  ensureConnected(reason: "tool"): Promise<IntercomClient>;
-  syncPresenceIdentity(sessionId: string): void;
-  resolveSessionTarget?(activeClient: IntercomClient, nameOrId: string): Promise<string | null>;
-  homeGroup(): string;
-  setJoinedGroup(group: string): void;
-  clearJoinedGroup(): void;
-  confirmSend: boolean;
-  /**
-   * Atomically reserve the single reply-waiter slot. Returns a structured
-   * refusal when another blocking ask already holds it, so concurrent calls
-   * never observe a rejected promise.
-   */
-  beginReplyWait(from: string, replyTo: string, signal?: AbortSignal): ReplyWaitAdmission;
-  replyTracker: ReplyTracker | (() => ReplyTracker);
-  /** Advisory fast-path check; beginReplyWait is the authoritative reservation. */
-  hasReplyWaiter(): boolean;
-}
-
-export function registerIntercomTool(pi: ExtensionAPI, deps: IntercomToolDeps): void {
-  const { childOrchestratorMetadata, ensureConnected, syncPresenceIdentity, beginReplyWait, hasReplyWaiter } = deps;
-  const resolveTarget = deps.resolveSessionTarget ?? resolveSessionTargetId;
-  const getMetadata = typeof childOrchestratorMetadata === "function"
-    ? childOrchestratorMetadata
-    : () => childOrchestratorMetadata ?? null;
-  const activeReplyTracker = (): ReplyTracker =>
-    typeof deps.replyTracker === "function" ? deps.replyTracker() : deps.replyTracker;
-  pi.registerTool({
-    name: "intercom",
-    label: "Intercom",
-    description: `Send a message to another local agent session running on this machine.
-Use this to communicate findings, request help, or coordinate work with other sessions.
-
-Sessions belong to an intercom group and can ONLY message sessions in the same group;
-cross-group sends are rejected by the broker. Ungrouped sessions share the "default" group.
-
-Usage:
-  intercom({ action: "list" })                    → List sessions in your group
-  intercom({ action: "list", group: "name" })     → Read-only peek at another group's sessions
-  intercom({ action: "join", group: "name" })     → Join or create a named group
-  intercom({ action: "leave" })                   → Return to your resolved home group
-  intercom({ action: "send", to: "session-name", message: "..." })  → Send message (own group only)
-  intercom({ action: "ask", to: "session-name", message: "..." })   → Ask and wait for reply
-  intercom({ action: "reply", message: "..." })                      → Reply to the active/single pending ask
-  intercom({ action: "pending" })                                      → List unresolved inbound asks
-  intercom({ action: "status" })                  → Show connection status and your group
-
-The "join" action changes this session's group in place. "default" is the shared
-default group; "true" and "auto" are reserved for subagent auto-groups. Joining
-does not grant cross-group access: contact_supervisor is the only cross-group path.`,
-    promptSnippet:
-      "Use to coordinate with other local agent sessions in your intercom group: list peers, send updates, ask for help, or check intercom connectivity. Groups are isolated; you can only message sessions in your own group.",
-
-    parameters: Type.Object({
-      action: Type.String({
-        description: "Action: 'list', 'join', 'leave', 'send', 'ask', 'reply', 'pending', or 'status'",
-      }),
-      to: Type.Optional(Type.String({
-        description: "Exact session name or exact full session ID (for 'send', 'ask', or targeted 'reply')",
-      })),
-      message: Type.Optional(Type.String({
-        description: "Message to send (for 'send', 'ask', or 'reply' action)",
-      })),
-      attachments: Type.Optional(Type.Array(Type.Object({
-        type: Type.Union([Type.Literal("file"), Type.Literal("snippet"), Type.Literal("context")]),
-        name: Type.String(),
-        content: Type.String(),
-        language: Type.Optional(Type.String()),
-      }))),
-      replyTo: Type.Optional(Type.String({
-        description: "Message ID to reply to (for threading or responding to an 'ask')",
-      })),
-      group: Type.Optional(Type.String({
-        description: "Group name for 'join'; read-only group filter for 'list'/'status'. 'send'/'ask' are locked to your own group.",
-      })),
-    }),
-
-    async execute(_toolCallId, params, _signal, _onUpdate, ctx) {
-      let connectedClient: IntercomClient;
-      try {
-        connectedClient = await ensureConnected("tool");
-      } catch (error) {
-        return {
-          content: [{ type: "text", text: `Intercom not connected: ${getErrorMessage(error)}` }],
-          isError: true,
-          details: { error: true },
-        };
-      }
-
-      syncPresenceIdentity(ctx.sessionManager.getSessionId());
-      const { action, to, message, attachments, replyTo, group } = params;
-      const requestedGroup = typeof group === "string" && group.trim() ? normalizeGroup(group) : undefined;
-      const resolveOwnGroup = async (): Promise<string> => {
-        const sessions = await connectedClient.listSessions();
-        const self = sessions.find((s) => s.id === connectedClient.sessionId);
-        return normalizeGroup(self?.group);
-      };
-      if ((action === "send" || action === "ask") && requestedGroup) {
-        const ownGroup = await resolveOwnGroup();
-        if (requestedGroup !== ownGroup) {
-          return {
-            content: [{ type: "text", text: `The 'group' parameter is read-only for 'list'/'status'. '${action}' is always locked to your own group ("${ownGroup}"); it cannot target group "${requestedGroup}".` }],
-            isError: true,
-            details: { error: true },
-          };
-        }
-      }
-
-      switch (action) {
-        case "join": {
-          let targetGroup: string;
-          try {
-            targetGroup = validateRuntimeGroup(group);
-          } catch (error) {
-            return {
-              content: [{ type: "text", text: getErrorMessage(error) }],
-              isError: true,
-              details: { error: true },
-            };
-          }
-          try {
-            const acknowledgedGroup = await connectedClient.updatePresenceAcked({ group: targetGroup });
-            if (acknowledgedGroup !== targetGroup) {
-              throw new Error(`Broker acknowledged group "${acknowledgedGroup}" instead of "${targetGroup}"`);
-            }
-            deps.setJoinedGroup(targetGroup);
-            return {
-              content: [{ type: "text", text: `Joined intercom group "${targetGroup}".` }],
-              isError: false,
-              details: { group: targetGroup },
-            };
-          } catch (error) {
-            return {
-              content: [{ type: "text", text: `Failed to join group: ${getErrorMessage(error)}` }],
-              isError: true,
-              details: { error: true },
-            };
-          }
-        }
-
-        case "leave": {
-          if (typeof group === "string" && group.trim().length > 0) {
-            return {
-              content: [{ type: "text", text: "The 'leave' action does not accept a group; it returns to the resolved home group." }],
-              isError: true,
-              details: { error: true },
-            };
-          }
-          let targetGroup: string;
-          try {
-            targetGroup = validateRuntimeGroup(deps.homeGroup());
-          } catch (error) {
-            return {
-              content: [{ type: "text", text: `Cannot leave intercom group: ${getErrorMessage(error)}` }],
-              isError: true,
-              details: { error: true },
-            };
-          }
-          try {
-            const acknowledgedGroup = await connectedClient.updatePresenceAcked({ group: targetGroup });
-            if (acknowledgedGroup !== targetGroup) {
-              throw new Error(`Broker acknowledged group "${acknowledgedGroup}" instead of "${targetGroup}"`);
-            }
-            deps.clearJoinedGroup();
-            return {
-              content: [{ type: "text", text: `Returned to home intercom group "${targetGroup}".` }],
-              isError: false,
-              details: { group: targetGroup },
-            };
-          } catch (error) {
-            return {
-              content: [{ type: "text", text: `Failed to leave group: ${getErrorMessage(error)}` }],
-              isError: true,
-              details: { error: true },
-            };
-          }
-        }
-
-        case "list": {
-          try {
-            const mySessionId = connectedClient.sessionId;
-            const ownSessions = await connectedClient.listSessions();
-            const currentSession = ownSessions.find(s => s.id === mySessionId);
-
-            if (!currentSession) {
-              return {
-                content: [{ type: "text", text: "Current session is missing from intercom session list." }],
-                isError: true,
-                details: { error: true },
-              };
-            }
-            const ownGroup = normalizeGroup(currentSession.group);
-
-            if (requestedGroup && requestedGroup !== ownGroup) {
-              const peeked = await connectedClient.listSessions(requestedGroup);
-              const section = peeked.length === 0
-                ? `**Group [${requestedGroup}] (read-only peek):**\nNo sessions in this group.`
-                : `**Group [${requestedGroup}] (read-only peek):**\n${peeked.map(s => formatSessionListRow(s, currentSession.cwd, s.id === mySessionId)).join("\n")}`;
-              return {
-                content: [{ type: "text", text: `Your group: ${ownGroup}\n\n${section}` }],
-                isError: false,
-                details: { group: ownGroup, peekGroup: requestedGroup },
-              };
-            }
-
-            const otherSessions = ownSessions.filter(s => s.id !== mySessionId);
-            const currentSection = `**Current session** (group: ${ownGroup}):\n${formatSessionListRow(currentSession, currentSession.cwd, true)}`;
-            const otherSection = otherSessions.length === 0
-              ? `**Other sessions:**\nNo other sessions in your group (${ownGroup}).`
-              : `**Other sessions** (group: ${ownGroup}):\n${otherSessions.map(s => formatSessionListRow(s, currentSession.cwd, false)).join("\n")}`;
-
-            return {
-              content: [{ type: "text", text: `${currentSection}\n\n${otherSection}` }],
-              isError: false,
-              details: { group: ownGroup },
-            };
-          } catch (error) {
-            return {
-              content: [{ type: "text", text: `Failed to list sessions: ${getErrorMessage(error)}` }],
-              isError: true,
-              details: { error: true },
-            };
-          }
-        }
-
-        case "send": {
-          if (!to || !message) {
-            return {
-              content: [{ type: "text", text: "Missing 'to' or 'message' parameter" }],
-              isError: true,
-              details: { error: true },
-            };
-          }
-          try {
-            const sendTo = await resolveTarget(connectedClient, to) ?? to;
-            if (sendTo === connectedClient.sessionId) {
-              return {
-                content: [{ type: "text", text: "Cannot message the current session" }],
-                isError: true,
-                details: { error: true },
-              };
-            }
-            if (!replyTo && deps.confirmSend && ctx.hasUI) {
-              const attachmentText = attachments?.length ? formatAttachments(attachments) : "";
-              const confirmed = await ctx.ui.confirm(
-                "Send Message",
-                `Send to "${to}":\n\n${message}${attachmentText}`,
-              );
-              if (!confirmed) {
-                return {
-                  content: [{ type: "text", text: "Message cancelled by user" }],
-                  isError: false,
-                  details: {},
-                };
-              }
-            }
-            const result = await connectedClient.send(sendTo, {
-              text: message,
-              attachments,
-              replyTo,
-            });
-            if (!result.delivered) {
-              const errorText = result.reason ?? "Session may not exist or has disconnected.";
-              return {
-                content: [{ type: "text", text: `Message to "${to}" was not delivered: ${errorText}` }],
-                isError: true,
-                details: { messageId: result.id, delivered: false, reason: result.reason },
-              };
-            }
-            pi.appendEntry("intercom_sent", {
-              to,
-              message: { text: message, attachments, replyTo },
-              messageId: result.id,
-              timestamp: Date.now(),
-            });
-            if (replyTo) {
-              activeReplyTracker().markReplied(replyTo);
-            }
-            return {
-              content: [{ type: "text", text: `Message sent to ${to}` }],
-              isError: false,
-              details: { messageId: result.id, delivered: true },
-            };
-          } catch (error) {
-            return {
-              content: [{ type: "text", text: `Failed to send: ${getErrorMessage(error)}` }],
-              isError: true,
-              details: { error: true },
-            };
-          }
-        }
-
-        case "ask": {
-          if (!to) {
-            return {
-              content: [{ type: "text", text: "Missing 'to' or 'message' parameter" }],
-              isError: true,
-              details: { error: true },
-            };
-          }
-
-          if (_signal?.aborted) {
-            return {
-              content: [{ type: "text", text: "Cancelled" }],
-              isError: true,
-              details: { error: true },
-            };
-          }
-          let wait: ReplyWait | null = null;
-
-          try {
-            const metadata = getMetadata();
-            const currentSupervisorId = connectedClient.supervisorSessionId ?? undefined;
-            const metadataSupervisorId = metadata?.supervisor?.supervisorSessionId;
-            const directParentTarget = Boolean(
-              metadata &&
-              (to === metadata.orchestratorTarget ||
-                to === currentSupervisorId ||
-                to === metadataSupervisorId),
-            );
-            const claimParentAsk = (resolvedTargetId: string): boolean =>
-              Boolean(
-                metadata &&
-                requestParentAskHandoff(pi.events, metadata, {
-                  kind: "intercom",
-                  question: typeof message === "string" ? message : "",
-                  attachments,
-                  resolvedTargetId,
-                }),
-              );
-            if (
-              directParentTarget &&
-              claimParentAsk(currentSupervisorId ?? metadataSupervisorId ?? to)
-            ) {
-              return {
-                content: [{ type: "text", text: "Parent ask claimed; this child is ending for a fresh subagent start." }],
-                isError: false,
-                details: { yielded: true },
-              };
-            }
-
-            const sendTo = await resolveTarget(connectedClient, to) ?? to;
-            if (_signal?.aborted) {
-              return {
-                content: [{ type: "text", text: "Cancelled" }],
-                isError: true,
-                details: { error: true },
-              };
-            }
-            if (sendTo === connectedClient.sessionId) {
-              return {
-                content: [{ type: "text", text: "Cannot message the current session" }],
-                isError: true,
-                details: { error: true },
-              };
-            }
-            if (metadata && !directParentTarget) {
-              const authoritativeParent = [currentSupervisorId, metadataSupervisorId].find(
-                (candidate) => candidate === sendTo,
-              );
-              const resolvedParent =
-                authoritativeParent ?? await resolveTarget(connectedClient, metadata.orchestratorTarget);
-              if (resolvedParent !== null && resolvedParent === sendTo && claimParentAsk(sendTo)) {
-                return {
-                  content: [{ type: "text", text: "Parent ask claimed; this child is ending for a fresh subagent start." }],
-                  isError: false,
-                  details: { yielded: true },
-                };
-              }
-            }
-            if (!message) {
-              return {
-                content: [{ type: "text", text: "Missing 'to' or 'message' parameter" }],
-                isError: true,
-                details: { error: true },
-              };
-            }
-            if (hasReplyWaiter()) {
-              return {
-                content: [{ type: "text", text: "Already waiting for a reply" }],
-                isError: true,
-                details: { error: true },
-              };
-            }
-            const questionId = randomUUID();
-            const admission = beginReplyWait(sendTo, questionId, _signal);
-            if (!admission.ok) {
-              return {
-                content: [{ type: "text", text: admission.reason === "busy" ? "Already waiting for a reply" : "Cancelled" }],
-                isError: true,
-                details: { error: true },
-              };
-            }
-            wait = admission.wait;
-            const sendResult = await connectedClient.send(sendTo, {
-              messageId: questionId,
-              text: message,
-              attachments,
-              replyTo,
-              expectsReply: true,
-            });
-
-            if (!sendResult.delivered) {
-              const errorText = sendResult.reason ?? "Session may not exist or has disconnected.";
-              wait.cancel(new Error(`Message to "${to}" was not delivered: ${errorText}`));
-              return {
-                content: [{ type: "text", text: `Message to "${to}" was not delivered: ${errorText}` }],
-                isError: true,
-                details: { error: true },
-              };
-            }
-            pi.appendEntry("intercom_sent", {
-              to,
-              message: { text: message, attachments, replyTo },
-              messageId: sendResult.id,
-              timestamp: Date.now(),
-            });
-            const replyMessage = await wait.promise;
-            const replyText = replyMessage.content.text;
-            const replyAttachments = replyMessage.content.attachments?.length
-              ? formatAttachments(replyMessage.content.attachments)
-              : "";
-            pi.appendEntry("intercom_received", {
-              from: to,
-              message: { text: replyText, attachments: replyMessage.content.attachments },
-              messageId: replyMessage.id,
-              timestamp: replyMessage.timestamp,
-            });
-            if (replyMessage.replyError !== undefined) {
-              return {
-                content: [{ type: "text", text: `Failed: ${replyMessage.replyError}` }],
-                isError: true,
-                details: { error: true, replyTo: replyMessage.replyTo },
-              };
-            }
-            return {
-              content: [{ type: "text", text: `**Reply from ${to}:**\n${replyText}${replyAttachments}` }],
-              isError: false,
-              details: {},
-            };
-          } catch (error) {
-            // Settle only this call's own waiter; a concurrent call's
-            // reservation must never be torn down from this failure path.
-            wait?.cancel(toError(error));
-            return {
-              content: [{ type: "text", text: `Failed: ${getErrorMessage(error)}` }],
-              isError: true,
-              details: { error: true },
-            };
-          }
-        }
-
-        case "reply": {
-          if (!message) {
-            return {
-              content: [{ type: "text", text: "Missing 'message' parameter" }],
-              isError: true,
-              details: { error: true },
-            };
-          }
-
-          try {
-            const target = activeReplyTracker().resolveReplyTarget({ to });
-            if (target.from.id === connectedClient.sessionId) {
-              return {
-                content: [{ type: "text", text: "Cannot message the current session" }],
-                isError: true,
-                details: { error: true },
-              };
-            }
-            const result = await connectedClient.send(target.from.id, {
-              text: message,
-              replyTo: target.message.id,
-            });
-            if (!result.delivered) {
-              const errorText = result.reason ?? "Session may not exist or has disconnected.";
-              return {
-                content: [{ type: "text", text: `Reply to "${target.from.name || target.from.id}" was not delivered: ${errorText}` }],
-                isError: true,
-                details: { messageId: result.id, delivered: false, reason: result.reason },
-              };
-            }
-            activeReplyTracker().markReplied(target.message.id);
-            pi.appendEntry("intercom_sent", {
-              to: target.from.name || target.from.id,
-              message: { text: message, replyTo: target.message.id },
-              messageId: result.id,
-              timestamp: Date.now(),
-            });
-            return {
-              content: [{ type: "text", text: `Reply sent to ${target.from.name || target.from.id}` }],
-              isError: false,
-              details: { messageId: result.id, delivered: true, replyTo: target.message.id },
-            };
-          } catch (error) {
-            return {
-              content: [{ type: "text", text: `Failed to reply: ${getErrorMessage(error)}` }],
-              isError: true,
-              details: { error: true },
-            };
-          }
-        }
-
-        case "pending": {
-          const pendingAsks = activeReplyTracker().listPending();
-          if (pendingAsks.length === 0) {
-            return {
-              content: [{ type: "text", text: "No unresolved inbound asks." }],
-              isError: false,
-              details: {},
-            };
-          }
-
-          const now = Date.now();
-          const lines = pendingAsks.map(({ from, message, receivedAt }) => {
-            const preview = message.content.text.replace(/\s+/g, " ").slice(0, 80);
-            const elapsedSeconds = Math.max(0, Math.floor((now - receivedAt) / 1000));
-            return `- ${from.name || from.id} · ${message.id} · ${elapsedSeconds}s ago · ${preview}`;
-          });
-          return {
-            content: [{ type: "text", text: `**Pending asks:**\n${lines.join("\n")}` }],
-            isError: false,
-            details: {},
-          };
-        }
-
-        case "status": {
-          try {
-            const mySessionId = connectedClient.sessionId;
-            const sessions = await connectedClient.listSessions();
-            const self = sessions.find((s) => s.id === mySessionId);
-            const ownGroup = normalizeGroup(self?.group);
-            const peekSection = requestedGroup && requestedGroup !== ownGroup
-              ? `\nPeeked group [${requestedGroup}]: ${(await connectedClient.listSessions(requestedGroup)).length} session(s)`
-              : "";
-            return {
-              content: [{
-                type: "text",
-                text: `**Intercom Status:**\nConnected: Yes\nSession ID: ${mySessionId}\nGroup: ${ownGroup}\nActive sessions in group: ${sessions.length}${peekSection}`,
-              }],
-              isError: false,
-              details: { group: ownGroup },
-            };
-          } catch (error) {
-            return {
-              content: [{ type: "text", text: `Failed to get status: ${getErrorMessage(error)}` }],
-              isError: true,
-              details: { error: true },
-            };
-          }
-        }
-
-        default:
-          return {
-            content: [{ type: "text", text: `Unknown action: ${action}` }],
-            isError: true,
-            details: { error: true },
-          };
-      }
-    },
-    renderCall(args, theme) {
-      const action = typeof args.action === "string" ? args.action : "intercom";
-      const target = typeof args.to === "string" && args.to.trim() ? args.to.trim() : undefined;
-      const messagePreview = previewText(args.message, 96);
-      const attachmentCount = Array.isArray(args.attachments) ? args.attachments.length : 0;
-      let text = theme.fg("toolTitle", theme.bold("intercom "));
-      text += theme.fg(action === "ask" ? "warning" : action === "reply" ? "success" : "accent", action);
-      if (target) {
-        text += " " + theme.fg("muted", "→") + " " + theme.fg("accent", target);
-      }
-      if (attachmentCount > 0) {
-        text += " " + theme.fg("dim", `(${attachmentCount} attachment${attachmentCount === 1 ? "" : "s"})`);
-      }
-      if (messagePreview) {
-        text += "\n  " + theme.fg("dim", messagePreview);
-      }
-      return new Text(text, 0, 0);
-    },
-    renderResult: renderIntercomResult,
-  });
-}