@fitchmultz/pi-subagents 0.44.6 → 0.45.0

package/src/pi-intercom/supervisor.ts

@@ -0,0 +1,362 @@
+import type { ExtensionAPI, ExtensionContext } from "@earendil-works/pi-coding-agent";
+import type { ReadonlyInput } from "../shared/types/inputs.ts";
+import type { Message, SendResult } from "./types.ts";
+import type { IntercomLifecycle } from "./lifecycle.ts";
+import { resolveConnectedTarget, type IntercomConnection } from "./connection.ts";
+import type { ReplyWait } from "./reply-wait.ts";
+import type {
+  ChildOrchestratorMetadata,
+  ContactSupervisorToolParams,
+  ToolResultLike,
+} from "./runtime-types.ts";
+import { formatChildOrchestratorMessage } from "./identity.ts";
+import {
+  formatSupervisorInterviewRequest,
+  parseStructuredSupervisorReply,
+  validateSupervisorInterviewRequest,
+  type SupervisorInterviewRequest,
+} from "./interview.ts";
+import { errorMessage } from "./validation.ts";
+import { formatAttachments } from "./message-format.ts";
+import { toolError, toolText } from "./tool-arguments.ts";
+import {
+  createSupervisorQuestion,
+  readQuestionState,
+  recordQuestionDelivery,
+  type SupervisorQuestion,
+} from "../runs/shared/supervisor-questions.ts";
+import { formatRunAction } from "../shared/status-format.ts";
+
+type Lifecycle = Readonly<Pick<IntercomLifecycle, "identity" | "markActivity">>;
+type Connection = Readonly<Pick<IntercomConnection, "ensure" | "syncIdentity" | "syncStatus">>;
+type ReplyWaitHandle = Readonly<
+  Pick<ReplyWait, "clearRetry" | "isWaitingFor" | "retarget" | "retry" | "wait" | "waiting">
+>;
+
+interface SupervisorOwners {
+  readonly pi: ExtensionAPI;
+  readonly lifecycle: Lifecycle;
+  readonly connection: Connection;
+  readonly wait: ReplyWaitHandle;
+}
+interface DecisionRequest {
+  readonly reason: "need_decision" | "interview_request";
+  readonly message?: string;
+  readonly interview?: SupervisorInterviewRequest;
+  readonly signal?: AbortSignal;
+  readonly ctx: ExtensionContext;
+}
+interface Notification {
+  readonly question: ReadonlyInput<SupervisorQuestion>;
+  readonly text: string;
+  readonly reason: DecisionRequest["reason"];
+}
+function validateContact(params: ContactSupervisorToolParams): ToolResultLike | undefined {
+  const { reason, message } = params;
+  if (!["need_decision", "progress_update", "interview_request"].includes(reason)) {
+    return toolError(
+      "Invalid reason. Use 'need_decision', 'interview_request', or 'progress_update'.",
+    );
+  }
+  if ((reason === "need_decision" || reason === "progress_update") && typeof message !== "string") {
+    return toolError(`Missing 'message' parameter for reason '${reason}'.`);
+  }
+  return;
+}
+function replyDetails(
+  questionId: string,
+  text: string,
+  interview: SupervisorInterviewRequest | undefined,
+): Readonly<Record<string, unknown>> {
+  const structured = interview ? parseStructuredSupervisorReply(text, interview) : undefined;
+  if (structured?.value) {
+    return { questionId, structuredReply: structured.value };
+  }
+  if (structured?.error !== undefined && structured.error !== "") {
+    return { questionId, structuredReplyParseError: structured.error };
+  }
+  return { questionId };
+}
+/** Owns durable supervisor questions and every wake-notification attempt. */
+export class IntercomSupervisor {
+  private readonly owners: SupervisorOwners;
+  private readonly metadata: ChildOrchestratorMetadata;
+  private readonly notifications = new Set<Promise<void>>();
+  constructor(owners: SupervisorOwners, metadata: ChildOrchestratorMetadata) {
+    this.owners = owners;
+    this.metadata = metadata;
+  }
+  async drain(): Promise<void> {
+    await Promise.allSettled(this.notifications);
+  }
+  private createQuestion(request: DecisionRequest): {
+    readonly question: ReadonlyInput<SupervisorQuestion>;
+    readonly text: string;
+  } {
+    const { reason, interview, ctx } = request;
+    const body = interview
+      ? formatSupervisorInterviewRequest(interview, request.message)
+      : (request.message ?? "");
+    const metadata = this.metadata;
+    const question = createSupervisorQuestion({
+      runId: metadata.runId,
+      ownerTarget: metadata.orchestratorTarget,
+      agent: metadata.agent,
+      index: Number(metadata.index),
+      childSessionId: ctx.sessionManager.getSessionId(),
+      childTarget:
+        metadata.sessionName ??
+        this.owners.lifecycle.identity(ctx.sessionManager.getSessionId()).name,
+      sessionFile: ctx.sessionManager.getSessionFile() ?? "",
+      cwd: ctx.cwd,
+      pid: process.pid,
+      reason,
+      message: body,
+      ...(interview ? { interview } : {}),
+    });
+    const text = formatChildOrchestratorMessage(
+      interview ? "interview" : "ask",
+      metadata,
+      [
+        `Question ID: ${question.questionId}`,
+        `Answer after reconnect/reload: ${formatRunAction("answer", question.runId, { questionId: question.questionId, message: "..." }, Number(process.env.PI_SUBAGENT_DEPTH) > 1)}`,
+        body,
+      ].join("\n"),
+    );
+    return { question, text };
+  }
+  private ownNotification(operation: () => Promise<void>): void {
+    const task = Promise.resolve().then(operation);
+    this.notifications.add(task);
+    task
+      .then(
+        () => {
+          this.notifications.delete(task);
+        },
+        (error: unknown) => {
+          this.notifications.delete(task);
+          console.error("Intercom supervisor notification failed:", error);
+        },
+      )
+      .catch((error: unknown) => {
+        console.error("Intercom supervisor notification cleanup failed:", error);
+      });
+  }
+  private scheduleNotification(notification: Notification): void {
+    let retryAfter = 0;
+    let failureLogged = false;
+    const { question, text, reason } = notification;
+    const active = () => this.owners.wait.isWaitingFor(question.questionId);
+    const logFailure = (error: unknown) => {
+      if (active() && !failureLogged) {
+        this.owners.pi.appendEntry("intercom_question_notification_error", {
+          questionId: question.questionId,
+          error: errorMessage(error),
+        });
+        failureLogged = true;
+      }
+    };
+    const recordNotification = (to: string, sent: SendResult) => {
+      if (sent.accepted || !failureLogged) {
+        this.owners.pi.appendEntry("intercom_sent", {
+          to,
+          messageId: question.questionId,
+          message: { text, reason },
+          accepted: sent.accepted,
+          timestamp: Date.now(),
+        });
+      }
+      failureLogged ||= !sent.accepted;
+    };
+    const notify = async () => {
+      if (!active() || Date.now() < retryAfter) {
+        return;
+      }
+      this.owners.wait.clearRetry(question.questionId);
+      let retry = true;
+      try {
+        const client = await this.owners.connection.ensure("tool");
+        if (!active()) {
+          return;
+        }
+        const to =
+          (await resolveConnectedTarget(client, this.metadata.orchestratorTarget)) ??
+          this.metadata.orchestratorTarget;
+        if (!active()) {
+          return;
+        }
+        this.owners.wait.retarget(question.questionId, to);
+        // A thrown send may have lost only its acknowledgement; replay only explicit rejection.
+        retry = false;
+        const sent = await client.send(to, {
+          text,
+          messageId: question.questionId,
+          expectsReply: true,
+          delivery: "steer",
+        });
+        if (!active()) {
+          return;
+        }
+        retry = !sent.accepted;
+        recordNotification(to, sent);
+      } catch (error) {
+        logFailure(error);
+      } finally {
+        if (retry && active()) {
+          retryAfter = Date.now() + 1000;
+          this.owners.wait.retry(question.questionId, () => {
+            this.ownNotification(notify);
+          });
+        }
+      }
+    };
+    this.ownNotification(notify);
+  }
+  private async decision(request: DecisionRequest): Promise<ToolResultLike> {
+    if (this.owners.wait.waiting) {
+      throw new Error("Already waiting for a reply");
+    }
+    if (request.signal?.aborted === true) {
+      throw new Error("Cancelled");
+    }
+    const { question, text } = this.createQuestion(request);
+    const reply = this.owners.wait.wait({
+      from: this.metadata.orchestratorTarget,
+      replyTo: question.questionId,
+      signal: request.signal,
+      question,
+    });
+    this.scheduleNotification({ question, text, reason: request.reason });
+    const message = await reply;
+    return this.answer(question, message, request.interview);
+  }
+  private answer(
+    question: ReadonlyInput<SupervisorQuestion>,
+    message: Message,
+    interview: SupervisorInterviewRequest | undefined,
+  ): ToolResultLike {
+    this.owners.pi.appendEntry("intercom_received", {
+      from: this.metadata.orchestratorTarget,
+      questionId: question.questionId,
+      message: message.content,
+      messageId: message.id,
+      timestamp: message.timestamp,
+    });
+    recordQuestionDelivery(question, {
+      kind: "live",
+      runId: question.runId,
+      deliveredAt: Date.now(),
+    });
+    const details = replyDetails(question.questionId, message.content.text, interview);
+    const origin = readQuestionState(question).answer?.origin;
+    return toolText(
+      `**${origin === "human" ? "Direct user answer (human origin)" : "Reply from supervisor"}:**\n${message.content.text}${formatAttachments(message.content.attachments ?? [])}`,
+      details,
+    );
+  }
+  private async progress(
+    message: string,
+    signal: AbortSignal | undefined,
+    ctx: ExtensionContext,
+  ): Promise<ToolResultLike> {
+    let client;
+    try {
+      client = await this.owners.connection.ensure("tool");
+    } catch (error) {
+      return toolError(`Intercom not connected: ${errorMessage(error)}`);
+    }
+    this.owners.connection.syncIdentity(ctx.sessionManager.getSessionId());
+    if (signal?.aborted === true) {
+      return toolError("Cancelled");
+    }
+    let to: string;
+    try {
+      to =
+        (await resolveConnectedTarget(client, this.metadata.orchestratorTarget)) ??
+        this.metadata.orchestratorTarget;
+    } catch (error) {
+      return toolError(`Failed to resolve supervisor target: ${errorMessage(error)}`);
+    }
+    if (this.cancelled(signal)) {
+      return toolError("Cancelled");
+    }
+    if (to === client.sessionId) {
+      return toolError("Cannot message the current session");
+    }
+    try {
+      const result = await client.send(to, {
+        text: formatChildOrchestratorMessage("update", this.metadata, message),
+        delivery: "steer",
+      });
+      return this.progressReceipt(message, result);
+    } catch (error) {
+      return toolError(`Failed to send progress update: ${errorMessage(error)}`);
+    }
+  }
+  private progressReceipt(message: string, result: SendResult): ToolResultLike {
+    if (!result.accepted) {
+      return toolError(
+        `Message to "${this.metadata.orchestratorTarget}" was not delivered: ${result.reason ?? "Session may not exist or has disconnected."}`,
+        {
+          messageId: result.id,
+          accepted: result.accepted,
+          delivered: false,
+          reason: result.reason,
+        },
+      );
+    }
+    this.owners.lifecycle.markActivity();
+    this.owners.connection.syncStatus();
+    this.owners.pi.appendEntry("intercom_sent", {
+      to: this.metadata.orchestratorTarget,
+      message: { text: message, reason: "progress_update" },
+      messageId: result.id,
+      timestamp: Date.now(),
+      subagent: {
+        runId: this.metadata.runId,
+        agent: this.metadata.agent,
+        index: this.metadata.index,
+      },
+    });
+    return toolText(
+      `Progress update accepted for supervisor ${this.metadata.orchestratorTarget}. Queued for the next tool boundary; broker acceptance does not confirm the supervisor has read or acted on it.`,
+      {
+        messageId: result.id,
+        accepted: result.accepted,
+        delivered: result.delivered,
+        queued: result.queued === true,
+      },
+    );
+  }
+  private cancelled(signal: AbortSignal | undefined): boolean {
+    return signal?.aborted === true;
+  }
+  async execute(
+    params: ContactSupervisorToolParams,
+    signal: AbortSignal | undefined,
+    ctx: ExtensionContext,
+  ): Promise<ToolResultLike> {
+    const { reason, message } = params;
+    const invalid = validateContact(params);
+    if (invalid) {
+      return invalid;
+    }
+    if (reason === "progress_update") {
+      return await this.progress(message ?? "", signal, ctx);
+    }
+    const validation =
+      reason === "interview_request"
+        ? validateSupervisorInterviewRequest(params.interview)
+        : undefined;
+    if (validation?.ok === false) {
+      return toolError(`Invalid interview request: ${validation.error}`);
+    }
+    return await this.decision({
+      reason,
+      message,
+      interview: validation?.ok === true ? validation.interview : undefined,
+      signal,
+      ctx,
+    });
+  }
+}

package/src/pi-intercom/tool-arguments.ts

@@ -0,0 +1,120 @@
+import type { IntercomToolParams, ToolResultLike } from "./runtime-types.ts";
+import { failureDetails } from "./tool-results.ts";
+export function toolError(
+  text: string,
+  details: Readonly<Record<string, unknown>> = { error: true },
+): ToolResultLike {
+  return { content: [{ type: "text", text }], isError: true, details };
+}
+export function toolText(
+  text: string,
+  details: Readonly<Record<string, unknown>> = {},
+): ToolResultLike {
+  return { content: [{ type: "text", text }], isError: false, details };
+}
+function deliveryError(params: IntercomToolParams): ToolResultLike | undefined {
+  const { action, delivery, passive } = params;
+  if (passive !== undefined && action !== "send") {
+    return toolError("'passive' is only valid for action='send'");
+  }
+  if (delivery === "passive" && action !== "send") {
+    return toolError(
+      "delivery='passive' is only valid for action='send'. Passive delivery is for human-visible breadcrumbs and is discouraged for agent-to-agent coordination; normal send defaults to steer. Use ask with delivery='steer' only when the sender must stay alive and cannot safely continue without the reply.",
+    );
+  }
+  const actionError = deliveryActionError(params);
+  if (actionError) {
+    return actionError;
+  }
+  if (passive === true && delivery !== undefined && delivery !== "passive") {
+    return toolError("'passive' cannot be combined with a non-passive delivery mode");
+  }
+  return;
+}
+function deliveryActionError(params: IntercomToolParams): ToolResultLike | undefined {
+  const { action, delivery, queueMode, threadId } = params;
+  if (
+    (delivery !== undefined || queueMode !== undefined || threadId !== undefined) &&
+    action !== "send" &&
+    action !== "ask"
+  ) {
+    const queue = queueMode !== undefined || delivery === "queue" || threadId !== undefined;
+    return toolError(
+      "'delivery', 'queueMode', and 'threadId' are only valid for action='send' or action='ask'",
+      failureDetails(
+        queue ? "invalid_queue_arguments" : "invalid_delivery_arguments",
+        [{ action: "send", guidance: "Use delivery options only with send or ask." }],
+        { error: true },
+      ),
+    );
+  }
+  return;
+}
+function queueError(params: IntercomToolParams): ToolResultLike | undefined {
+  const { threadId, queueMode } = params;
+  if (threadId !== undefined && queueMode !== "replace") {
+    return toolError(
+      "'threadId' is only valid with queueMode='replace'",
+      failureDetails(
+        "invalid_queue_arguments",
+        [
+          {
+            action: "send",
+            guidance: "Use threadId only with delivery='queue' and queueMode='replace'.",
+          },
+        ],
+        { error: true },
+      ),
+    );
+  }
+  if (queueMode === "replace" && (threadId === undefined || threadId.trim() === "")) {
+    return toolError(
+      "queueMode='replace' requires a non-empty threadId",
+      failureDetails(
+        "invalid_queue_arguments",
+        [
+          {
+            action: "send",
+            guidance: "Provide a non-empty threadId with delivery='queue' and queueMode='replace'.",
+          },
+        ],
+        { error: true },
+      ),
+    );
+  }
+  const delivery = params.passive === true ? "passive" : params.delivery;
+  if (queueMode !== undefined && delivery !== "queue") {
+    return toolError(
+      "'queueMode' is only valid with delivery='queue'. Use queue only for intentionally deferred work; otherwise omit queueMode and use default-steered send for live agent coordination. Avoid passive for agent-to-agent coordination.",
+      failureDetails(
+        "invalid_queue_arguments",
+        [{ action: "send", guidance: "Set delivery='queue', or omit queueMode and threadId." }],
+        { error: true },
+      ),
+    );
+  }
+  return;
+}
+export function validateIntercomArguments(params: IntercomToolParams): ToolResultLike | undefined {
+  if (params.scope !== undefined && params.action !== "list" && params.action !== "status") {
+    return toolError("'scope' is only valid for action='list' or action='status'");
+  }
+  return deliveryError(params) ?? queueError(params);
+}
+export function sendOptions(params: IntercomToolParams): {
+  readonly text: string;
+  readonly attachments: IntercomToolParams["attachments"];
+  readonly replyTo: string | undefined;
+  readonly delivery: IntercomToolParams["delivery"];
+  readonly queueMode: IntercomToolParams["queueMode"];
+  readonly threadId: string | undefined;
+} {
+  return {
+    text: params.message ?? "",
+    attachments: params.attachments,
+    replyTo: params.replyTo,
+    delivery: params.passive === true ? "passive" : params.delivery,
+    queueMode: params.queueMode,
+    threadId: params.threadId?.trim(),
+  };
+}

package/src/pi-intercom/tool-registration.ts

@@ -0,0 +1,121 @@
+import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+import type { IntercomTools } from "./tools.ts";
+import type { IntercomSupervisor } from "./supervisor.ts";
+import type { ToolResultLike } from "./runtime-types.ts";
+import { Type } from "../shared/native-typebox.ts";
+import { activateTools } from "../shared/lazy-tools.ts";
+import { throwIfToolError } from "./tool-results.ts";
+import { intercomSchema, contactSupervisorSchema } from "./tool-schemas.ts";
+import {
+  renderContactCall,
+  renderContactResult,
+  renderIntercomCall,
+  renderIntercomResult,
+} from "./ui/tool-renderers.ts";
+type MessagingTool = Readonly<Pick<IntercomTools, "execute">>;
+type SupervisorTool = Readonly<Pick<IntercomSupervisor, "execute">>;
+
+function nativeResult(result: ToolResultLike): {
+  content: { type: "text"; text: string }[];
+  details: Readonly<Record<string, unknown>> | undefined;
+  isError: false;
+} {
+  const success = throwIfToolError(result);
+  return { content: [...success.content], details: success.details, isError: false };
+}
+function registerContact(pi: ExtensionAPI, supervisor: SupervisorTool): void {
+  pi.registerTool({
+    name: "contact_supervisor",
+    label: "Contact Supervisor",
+    description:
+      "Subagent-only tool for contacting the supervisor agent that delegated this task. Use need_decision only when this child cannot safely continue without a decision, approval, or product/API/scope clarification; this steers the supervisor at its next tool boundary and keeps the child alive for the reply. Use interview_request only when multiple structured answers are all required before safe progress; this also steers and waits. Use progress_update only for a discovery or change the supervisor needs while working; it steers at the next tool boundary without waiting for a reply. Skip starts, redundant status, and routine completion; retain material findings in the final result.",
+    promptSnippet:
+      "Subagent-only: steer the supervisor for required decisions, structured interviews, or material discoveries needed during active work. Skip routine status and completion messages.",
+    promptGuidelines: [
+      "Use contact_supervisor with reason='need_decision' when a subagent cannot safely continue without a decision, approval, or product/API/scope clarification; it steers the supervisor and waits for the reply.",
+      "Use contact_supervisor with reason='interview_request' only when the child cannot safely continue until it receives multiple structured answers in one blocking steered exchange.",
+      "Use contact_supervisor with reason='progress_update' only for a discovery or change the supervisor needs while working. It steers at the next tool boundary without waiting. Skip starts, redundant narration, and routine completion; keep material findings in the final result.",
+      "Do not use contact_supervisor for routine completion handoffs; return the final subagent result normally.",
+    ],
+    parameters: contactSupervisorSchema,
+    async execute(_id, params, signal, _update, ctx) {
+      return nativeResult(await supervisor.execute(params, signal, ctx));
+    },
+    renderCall: renderContactCall,
+    renderResult: renderContactResult,
+  });
+}
+function registerLoader(pi: ExtensionAPI): void {
+  pi.registerTool({
+    name: "load_intercom",
+    label: "Load Intercom",
+    description:
+      "Enable local peer coordination: list/check sessions before shared-state work, send or reply to messages, and inspect/publish topics. Does not send a message or check peers itself.",
+    parameters: Type.Object({}),
+    async execute() {
+      if (
+        !pi.getAllTools().some((tool) => tool.name === "intercom" && tool.namespace === undefined)
+      ) {
+        throw new Error("Intercom is excluded from this session.");
+      }
+      activateTools(pi, ["intercom"]);
+      return {
+        content: [
+          {
+            type: "text",
+            text: "Intercom enabled. Use intercom({action:'list'}) to check peers, or status, pending, reply, send, ask and topics for coordination.",
+          },
+        ],
+        details: {},
+      };
+    },
+  });
+}
+function registerMessaging(pi: ExtensionAPI, tools: MessagingTool): void {
+  pi.registerTool({
+    name: "intercom",
+    defaultActive: false,
+    label: "Intercom",
+    description: `Send a message to another pi session running on this machine.
+Use this to communicate findings, request help, or coordinate work with other sessions.
+Non-blocking send defaults to steer for guidance, answers, corrections, or blockers that may affect active work. Use queue only when delay is intentional; use ask only when this process must remain alive waiting for the reply.
+
+Usage:
+  intercom({ action: "list" })                    → List sessions in this repository and its worktrees
+  intercom({ action: "list", scope: "all" })      → List connected sessions across every project
+  intercom({ action: "send", to: "session-name", message: "..." })  → Send live coordination (defaults to steer)
+  intercom({ action: "ask", to: "session-name", delivery: "steer", message: "..." })   → Blocking wait only when sender must stay alive
+  intercom({ action: "reply", message: "..." })                      → Reply to the active/single pending ask
+  intercom({ action: "pending" })                                      → List unresolved inbound asks
+  intercom({ action: "status" })                  → Show connection status
+  intercom({ action: "subscribe", topic: "project/work", awaitRelease: true }) → Opt into a topic
+  intercom({ action: "publish", topic: "project/work", message: "Current self-contained state" }) → Quiet latest state
+  intercom({ action: "topics" }) → Inspect topics and current resource owners`,
+    promptSnippet:
+      "Coordinate with local Pi sessions. Non-blocking send defaults to steer for live agent guidance; queue only for intentional delay and ask only for a required blocking reply.",
+    promptGuidelines: [
+      "Intercom list/status defaults to the current Git repository and its worktrees. Use scope='all' only when intentionally discovering sessions in other projects.",
+      "Action='send' defaults to delivery='steer' for agent-to-agent guidance, answers, corrections, blockers, or other context that may affect active work.",
+      "Use delivery='queue' only when delay is intentional. For routine status, explicitly subscribe/publish topics: updates replace quiet inspectable state outside model context, not passive conversation messages. Topic blockers/decisions and awaited ownership releases interrupt; direct messages always bypass subscriptions.",
+      "Treat inbound steered messages as supplemental coordination within the active task: incorporate relevant context and continue; replace the task only when the message explicitly says so.",
+      "Use action='reply' for an active inbound ask. Otherwise respond with send plus steer; use blocking ask only when this process must stay alive and cannot safely continue without the answer.",
+    ],
+    parameters: intercomSchema,
+    async execute(_id, params, signal, _update, ctx) {
+      return nativeResult(await tools.execute(params, signal, ctx));
+    },
+    renderCall: renderIntercomCall,
+    renderResult: renderIntercomResult,
+  });
+}
+export function registerIntercomTools(
+  pi: ExtensionAPI,
+  tools: MessagingTool,
+  supervisor: SupervisorTool | null,
+): void {
+  if (supervisor) {
+    registerContact(pi, supervisor);
+  }
+  registerLoader(pi);
+  registerMessaging(pi, tools);
+}

package/src/pi-intercom/tool-results.ts

@@ -0,0 +1,54 @@
+import type { SendResult } from "./types.ts";
+import type { ToolResultLike } from "./runtime-types.ts";
+export interface RecoveryAction {
+  readonly action: "list" | "pending" | "send" | "status";
+  readonly guidance?: string;
+}
+export function failureDetails(
+  reasonCode: string,
+  nextActions: readonly RecoveryAction[],
+  details: Readonly<Record<string, unknown>> = {},
+): Readonly<Record<string, unknown>> {
+  return { ...details, reasonCode, nextActions };
+}
+export function replyFailureReason(
+  message: string,
+): "no_pending_reply" | "ambiguous_reply_target" | "reply_failed" {
+  if (message.startsWith("No active intercom context") || message.startsWith("No pending ask")) {
+    return "no_pending_reply";
+  }
+  if (message.startsWith("Multiple pending asks") || message.includes("too short")) {
+    return "ambiguous_reply_target";
+  }
+  return "reply_failed";
+}
+export function firstTextContent(result: {
+  readonly content?: readonly { readonly type: string; readonly text?: string }[];
+}): string {
+  return (
+    result.content
+      ?.find((item) => item.type === "text" && typeof item.text === "string")
+      ?.text?.replace(/\*\*/g, "") ?? ""
+  );
+}
+export class ToolExecutionFailure extends Error {
+  readonly details?: Readonly<Record<string, unknown>>;
+  constructor(message: string, details?: Readonly<Record<string, unknown>>) {
+    super(message);
+    this.details = details;
+  }
+}
+export class AskDeliveryError extends Error {
+  readonly result: SendResult;
+  constructor(result: SendResult) {
+    super(result.reason ?? "Session may not exist or has disconnected.");
+    this.result = result;
+  }
+}
+export function throwIfToolError(result: ToolResultLike): ToolResultLike {
+  if (result.isError !== true) {
+    return result;
+  }
+  const text = firstTextContent(result);
+  throw new ToolExecutionFailure(text === "" ? "Tool failed" : text, result.details);
+}