@fitchmultz/pi-subagents 0.44.6 → 0.45.0

package/src/pi-intercom/reply-tracker.ts

@@ -2,12 +2,15 @@ import type { Message, SessionInfo } from "./types.ts";
 import { formatSessionTarget, resolveSessionTarget, shortSessionId } from "./session-targets.ts";
 
 export interface IntercomContext {
-  from: SessionInfo;
-  message: Message;
-  receivedAt: number;
+  readonly from: SessionInfo;
+  readonly message: Message;
+  readonly receivedAt: number;
 }
 
-function resolveBySenderTarget(contexts: IntercomContext[], to: string): IntercomContext[] {
+function resolveBySenderTarget(
+  contexts: readonly IntercomContext[],
+  to: string,
+): IntercomContext[] {
   const sessions = contexts.map((context) => context.from);
   const resolution = resolveSessionTarget(sessions, to);
   if (resolution.status === "none" || resolution.status === "prefix_too_short") {
@@ -17,8 +20,14 @@ function resolveBySenderTarget(contexts: IntercomContext[], to: string): Interco
   return contexts.filter((context) => matchingIds.has(context.from.id));
 }
 
-function tooShortSenderTargetMessage(contexts: IntercomContext[], to: string): string | null {
-  const resolution = resolveSessionTarget(contexts.map((context) => context.from), to);
+function tooShortSenderTargetMessage(
+  contexts: readonly IntercomContext[],
+  to: string,
+): string | null {
+  const resolution = resolveSessionTarget(
+    contexts.map((context) => context.from),
+    to,
+  );
   if (resolution.status !== "prefix_too_short") {
     return null;
   }
@@ -27,10 +36,16 @@ function tooShortSenderTargetMessage(contexts: IntercomContext[], to: string): s
   return `Pending ask target "${to}" is too short. Use one of: ${pendingSenderOptions(matches, contexts)}.`;
 }
 
-function pendingSenderOptions(contexts: IntercomContext[], allContexts: IntercomContext[] = contexts): string {
+function pendingSenderOptions(
+  contexts: readonly IntercomContext[],
+  allContexts: readonly IntercomContext[] = contexts,
+): string {
   const allSenders = allContexts.map((context) => context.from);
   return contexts
-    .map((context) => `${context.from.name || shortSessionId(context.from.id)}: to: ${JSON.stringify(formatSessionTarget(context.from, allSenders))} or replyTo: ${JSON.stringify(context.message.id)}`)
+    .map(
+      (context) =>
+        `${context.from.name === undefined || context.from.name === "" ? shortSessionId(context.from.id) : context.from.name}: to: ${JSON.stringify(formatSessionTarget(context.from, allSenders))} or replyTo: ${JSON.stringify(context.message.id)}`,
+    )
     .join(", ");
 }
 
@@ -38,6 +53,45 @@ export function isDurableSupervisorQuestion(message: Message): boolean {
   return message.content.text.includes(`Question ID: ${message.id}`);
 }
 
+function matchingSender(
+  contexts: readonly IntercomContext[],
+  to: string,
+): readonly IntercomContext[] {
+  const tooShort = tooShortSenderTargetMessage(contexts, to);
+  if (tooShort !== null && tooShort !== "") {
+    throw new Error(tooShort);
+  }
+  return resolveBySenderTarget(contexts, to);
+}
+function explicitReply(
+  contexts: readonly IntercomContext[],
+  replyTo: string,
+  to: string,
+): IntercomContext {
+  const target = contexts.find((context) => context.message.id === replyTo);
+  if (!target) {
+    throw new Error(`No pending ask with replyTo "${replyTo}"`);
+  }
+  if (
+    to !== "" &&
+    !matchingSender(contexts, to).some((context) => context.message.id === target.message.id)
+  ) {
+    throw new Error(`Pending ask "${replyTo}" is not from "${to}"`);
+  }
+  return target;
+}
+function replyBySender(contexts: readonly IntercomContext[], to: string): IntercomContext {
+  const matches = matchingSender(contexts, to);
+  if (matches.length === 1) {
+    return matches[0];
+  }
+  if (matches.length > 1) {
+    throw new Error(
+      `Multiple pending asks from "${to}" — use one of: ${pendingSenderOptions(matches, contexts)}.`,
+    );
+  }
+  throw new Error(`No pending ask from "${to}"`);
+}
 export class ReplyTracker {
   private readonly pendingAsks = new Map<string, IntercomContext>();
   private readonly pendingTurnContexts: IntercomContext[] = [];
@@ -49,9 +103,13 @@ export class ReplyTracker {
     this.askTimeoutMs = askTimeoutMs;
   }
 
-  recordIncomingMessage(from: SessionInfo, message: Message, receivedAt = Date.now()): IntercomContext {
+  recordIncomingMessage(
+    from: SessionInfo,
+    message: Message,
+    receivedAt = Date.now(),
+  ): IntercomContext {
     const context = { from, message, receivedAt };
-    if (message.expectsReply) {
+    if (message.expectsReply === true) {
       this.pruneExpired(receivedAt);
       this.pendingAsks.set(message.id, context);
     }
@@ -59,8 +117,12 @@ export class ReplyTracker {
   }
 
   queueTurnContext(context: IntercomContext): void {
-    if (!context.message.expectsReply) return;
-    if (this.hasTurnContext(context.message.id)) return;
+    if (context.message.expectsReply !== true) {
+      return;
+    }
+    if (this.hasTurnContext(context.message.id)) {
+      return;
+    }
     this.pendingTurnContexts.push(context);
   }
 
@@ -93,7 +155,8 @@ export class ReplyTracker {
   }
 
   expireSender(sessionId: string): number {
-    const expires = (context: IntercomContext) => context.from.id === sessionId && !isDurableSupervisorQuestion(context.message);
+    const expires = (context: IntercomContext) =>
+      context.from.id === sessionId && !isDurableSupervisorQuestion(context.message);
     let expired = 0;
     for (const [messageId, context] of this.pendingAsks) {
       if (expires(context)) {
@@ -103,7 +166,8 @@ export class ReplyTracker {
     }
     const beforeQueued = this.pendingTurnContexts.length;
     for (let index = this.pendingTurnContexts.length - 1; index >= 0; index -= 1) {
-      if (expires(this.pendingTurnContexts[index]!)) {
+      const context = this.pendingTurnContexts[index];
+      if (expires(context)) {
         this.pendingTurnContexts.splice(index, 1);
       }
     }
@@ -119,59 +183,39 @@ export class ReplyTracker {
     return expired;
   }
 
-  resolveReplyTarget(options: { to?: string; replyTo?: string }, now = Date.now()): IntercomContext {
+  resolveReplyTarget(
+    options: { readonly to?: string; readonly replyTo?: string },
+    now = Date.now(),
+  ): IntercomContext {
     this.pruneExpired(now);
 
     const pending = Array.from(this.pendingAsks.values());
     const contexts = this.currentTurnContext
-      ? [this.currentTurnContext, ...pending.filter((context) => context.message.id !== this.currentTurnContext?.message.id)]
+      ? [
+          this.currentTurnContext,
+          ...pending.filter(
+            (context) => context.message.id !== this.currentTurnContext?.message.id,
+          ),
+        ]
       : pending;
 
-    if (options.replyTo) {
-      const target = contexts.find((context) => context.message.id === options.replyTo);
-      if (!target) {
-        throw new Error(`No pending ask with replyTo "${options.replyTo}"`);
-      }
-      if (options.to) {
-        const tooShortMessage = tooShortSenderTargetMessage(contexts, options.to);
-        if (tooShortMessage) {
-          throw new Error(tooShortMessage);
-        }
-        const senderMatches = resolveBySenderTarget(contexts, options.to);
-        if (!senderMatches.some((context) => context.message.id === target.message.id)) {
-          throw new Error(`Pending ask "${options.replyTo}" is not from "${options.to}"`);
-        }
-      }
-      return target;
+    const replyTo = options.replyTo ?? "";
+    const to = options.to ?? "";
+    if (replyTo !== "") {
+      return explicitReply(contexts, replyTo, to);
     }
-
-    if (options.to) {
-      const tooShortMessage = tooShortSenderTargetMessage(contexts, options.to);
-      if (tooShortMessage) {
-        throw new Error(tooShortMessage);
-      }
-      const matches = resolveBySenderTarget(contexts, options.to);
-      if (matches.length === 1) {
-        return matches[0]!;
-      }
-      if (matches.length > 1) {
-        throw new Error(`Multiple pending asks from \"${options.to}\" — use one of: ${pendingSenderOptions(matches, contexts)}.`);
-      }
-      throw new Error(`No pending ask from \"${options.to}\"`);
+    if (to !== "") {
+      return replyBySender(contexts, to);
     }
-
     if (this.currentTurnContext) {
       return this.currentTurnContext;
     }
-
     if (pending.length === 1) {
-      return pending[0]!;
+      return pending[0];
     }
-
     if (pending.length === 0) {
       throw new Error("No active intercom context to reply to");
     }
-
     throw new Error("Multiple pending asks — specify `to`");
   }
 
@@ -180,7 +224,12 @@ export class ReplyTracker {
   }
 
   get hasReplyContext(): boolean {
-    return this.pendingAsks.size > 0 || this.pendingTurnContexts.length > 0 || this.currentTurnContext !== null || this.activeAgentContext !== null;
+    return (
+      this.pendingAsks.size > 0 ||
+      this.pendingTurnContexts.length > 0 ||
+      this.currentTurnContext !== null ||
+      this.activeAgentContext !== null
+    );
   }
 
   listPending(now = Date.now()): IntercomContext[] {
@@ -189,23 +238,36 @@ export class ReplyTracker {
   }
 
   private hasTurnContext(messageId: string): boolean {
-    return this.pendingTurnContexts.some((context) => context.message.id === messageId)
-      || this.currentTurnContext?.message.id === messageId
-      || this.activeAgentContext?.message.id === messageId;
+    return (
+      this.pendingTurnContexts.some((context) => context.message.id === messageId) ||
+      this.currentTurnContext?.message.id === messageId ||
+      this.activeAgentContext?.message.id === messageId
+    );
   }
 
   private removeContext(messageId: string): void {
     this.pendingAsks.delete(messageId);
     for (let index = this.pendingTurnContexts.length - 1; index >= 0; index -= 1) {
-      if (this.pendingTurnContexts[index]?.message.id === messageId) this.pendingTurnContexts.splice(index, 1);
+      if (this.pendingTurnContexts[index]?.message.id === messageId) {
+        this.pendingTurnContexts.splice(index, 1);
+      }
+    }
+    if (this.currentTurnContext?.message.id === messageId) {
+      this.currentTurnContext = null;
+    }
+    if (this.activeAgentContext?.message.id === messageId) {
+      this.activeAgentContext = null;
     }
-    if (this.currentTurnContext?.message.id === messageId) this.currentTurnContext = null;
-    if (this.activeAgentContext?.message.id === messageId) this.activeAgentContext = null;
   }
 
   private pruneExpired(now: number): void {
     for (const [messageId, context] of this.pendingAsks) {
-      if (!isDurableSupervisorQuestion(context.message) && now - context.receivedAt > this.askTimeoutMs) this.removeContext(messageId);
+      if (
+        !isDurableSupervisorQuestion(context.message) &&
+        now - context.receivedAt > this.askTimeoutMs
+      ) {
+        this.removeContext(messageId);
+      }
     }
   }
 }

package/src/pi-intercom/reply-wait.ts

@@ -0,0 +1,247 @@
+import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+import type { ReadonlyInput } from "../shared/types/inputs.ts";
+import type { Message } from "./types.ts";
+import type { IntercomClient, SendResult } from "./broker/client.ts";
+import type { IntercomTransport } from "./transport.ts";
+import type { IntercomLifecycle } from "./lifecycle.ts";
+import { RECIPIENT_TURN_FAILED_ATTACHMENT } from "./runtime-types.ts";
+import { asError } from "./validation.ts";
+import { AskDeliveryError } from "./tool-results.ts";
+import {
+  cancelSupervisorQuestion,
+  readQuestionState,
+  saveQuestionAnswer,
+  type SupervisorQuestion,
+} from "../runs/shared/supervisor-questions.ts";
+
+type Lifecycle = Readonly<Pick<IntercomLifecycle, "live" | "markActivity">>;
+
+interface ReplyWaiter {
+  readonly from: string;
+  readonly replyTo: string;
+  readonly question?: ReadonlyInput<SupervisorQuestion>;
+  readonly retryNotification?: () => void;
+  readonly resolve: (message: Message) => void;
+  readonly reject: (error: Readonly<Error>) => void;
+}
+export interface ReplyWaitOptions {
+  readonly from: string;
+  readonly replyTo: string;
+  readonly signal?: AbortSignal;
+  readonly question?: ReadonlyInput<SupervisorQuestion>;
+}
+export interface AskTransaction {
+  readonly to: string;
+  readonly questionId: string;
+  readonly options: Parameters<IntercomClient["send"]>[1];
+  readonly signal?: AbortSignal;
+  readonly onSent: (result: SendResult) => void;
+}
+/** Owns the single blocking wait, abort listener, timeout and durable polling. */
+export class ReplyWait {
+  private waiter: ReplyWaiter | null = null;
+  private readonly pi: ExtensionAPI;
+  private readonly lifecycle: Lifecycle;
+  private readonly timeoutMs: number;
+  constructor(pi: ExtensionAPI, lifecycle: Lifecycle, timeoutMs: number) {
+    this.pi = pi;
+    this.lifecycle = lifecycle;
+    this.timeoutMs = timeoutMs;
+  }
+  get waiting(): boolean {
+    return this.waiter !== null;
+  }
+  get durable(): boolean {
+    return this.waiter?.question !== undefined;
+  }
+  isWaitingFor(id: string): boolean {
+    return this.waiter?.replyTo === id;
+  }
+  retarget(id: string, from: string): void {
+    if (this.waiter?.replyTo === id) {
+      this.waiter = { ...this.waiter, from };
+    }
+  }
+  clearRetry(id: string): void {
+    if (this.waiter?.replyTo === id) {
+      this.waiter = { ...this.waiter, retryNotification: undefined };
+    }
+  }
+  retry(id: string, retryNotification: () => void): void {
+    if (this.waiter?.replyTo === id) {
+      this.waiter = { ...this.waiter, retryNotification };
+    }
+  }
+  reject(error: Readonly<Error>): void {
+    this.waiter?.reject(error);
+  }
+  peerDisconnected(id: string): void {
+    if (this.waiter?.from === id && !this.waiter.question) {
+      this.reject(new Error(`Reply peer disconnected before answering: ${id}`));
+    }
+  }
+  receive(
+    sender: { readonly id: string; readonly name?: string },
+    message: Message,
+    onMatch: () => void,
+  ): boolean {
+    const { id: from, name } = sender;
+    const waiter = this.waiter;
+    if (!waiter) {
+      return false;
+    }
+    const senderTarget = name !== undefined && name !== "" ? name : from;
+    if (
+      (senderTarget.toLowerCase() !== waiter.from.toLowerCase() && from !== waiter.from) ||
+      message.replyTo !== waiter.replyTo
+    ) {
+      return false;
+    }
+    onMatch();
+    waiter.resolve(message);
+    return true;
+  }
+  private poll(question: ReadonlyInput<SupervisorQuestion>, replyTo: string): void {
+    try {
+      const saved = readQuestionState(question);
+      if (saved.state === "cancelled") {
+        this.lifecycle.live()?.abort();
+        this.reject(new Error("Cancelled"));
+        return;
+      }
+      if (saved.answer) {
+        this.waiter?.resolve({
+          id: replyTo,
+          replyTo,
+          timestamp: saved.answer.answeredAt,
+          content: { text: saved.answer.message },
+        });
+      } else {
+        this.waiter?.retryNotification?.();
+      }
+    } catch (error) {
+      this.reject(asError(error));
+    }
+  }
+  private saveAnswer(
+    question: ReadonlyInput<SupervisorQuestion> | undefined,
+    message: Message,
+  ): boolean {
+    if (!question) {
+      return true;
+    }
+    if (
+      message.content.attachments?.some(
+        (attachment) => attachment.name === RECIPIENT_TURN_FAILED_ATTACHMENT,
+      ) === true
+    ) {
+      this.pi.appendEntry("intercom_question_notification_error", {
+        questionId: question.questionId,
+        error: message.content.text,
+      });
+      return false;
+    }
+    saveQuestionAnswer(question, message.content.text);
+    return true;
+  }
+  wait(options: ReplyWaitOptions): Promise<Message> {
+    if (this.waiter) {
+      throw new Error("Already waiting for a reply");
+    }
+    if (options.signal?.aborted === true) {
+      throw new Error("Cancelled");
+    }
+    return new Promise((resolve, reject) => {
+      const { from, replyTo, signal, question } = options;
+      const timeout = question
+        ? undefined
+        : setTimeout(() => {
+            this.reject(
+              new Error(
+                `No reply from "${from}" within ${Math.max(1, Math.round(this.timeoutMs / 60000))} minute(s)`,
+              ),
+            );
+          }, this.timeoutMs);
+      timeout?.unref();
+      const poll = question
+        ? setInterval(() => {
+            this.poll(question, replyTo);
+          }, 250)
+        : undefined;
+      const cleanup = () => {
+        clearTimeout(timeout);
+        clearInterval(poll);
+        signal?.removeEventListener("abort", onAbort);
+        if (this.waiter?.replyTo === replyTo) {
+          this.waiter = null;
+        }
+      };
+      const onAbort = () => {
+        try {
+          if (question) {
+            cancelSupervisorQuestion(question);
+          }
+        } finally {
+          cleanup();
+          reject(new Error("Cancelled"));
+        }
+      };
+      signal?.addEventListener("abort", onAbort, { once: true });
+      this.waiter = {
+        from,
+        replyTo,
+        question,
+        resolve: (message) => {
+          try {
+            if (!this.saveAnswer(question, message)) {
+              return;
+            }
+            cleanup();
+            resolve(message);
+          } catch (error) {
+            cleanup();
+            reject(asError(error));
+          }
+        },
+        reject: (error) => {
+          cleanup();
+          reject(error);
+        },
+      };
+    });
+  }
+  async transact(activeClient: IntercomTransport, transaction: AskTransaction): Promise<Message> {
+    const { to, questionId, options, signal, onSent } = transaction;
+    const reply = this.wait({ from: to, replyTo: questionId, signal });
+    // Delivery may reject before the reply is joined; the transaction owns both branches.
+    reply.catch(() => {
+      /* The original error is propagated below after cleanup. */
+    });
+    try {
+      if (signal?.aborted === true) {
+        throw new Error("Cancelled");
+      }
+      const result = await activeClient.send(to, {
+        ...options,
+        messageId: questionId,
+        expectsReply: true,
+      });
+      if (!result.accepted) {
+        throw new AskDeliveryError(result);
+      }
+      this.lifecycle.markActivity();
+      onSent(result);
+      return await reply;
+    } catch (error) {
+      if (this.isWaitingFor(questionId)) {
+        this.reject(asError(error));
+      }
+      try {
+        await reply;
+      } catch {
+        /* Preserve the delivery failure rather than its cleanup rejection. */
+      }
+      throw error;
+    }
+  }
+}

package/src/pi-intercom/runtime-types.ts

@@ -0,0 +1,97 @@
+import type { ExtensionContext } from "@earendil-works/pi-coding-agent";
+import type {
+  Attachment,
+  Message,
+  MessageDelivery,
+  QueueMode,
+  SessionInfo,
+  TopicUpdate,
+} from "./types.ts";
+
+export interface ChildOrchestratorMetadata {
+  readonly orchestratorTarget: string;
+  readonly runId: string;
+  readonly agent: string;
+  readonly index: string;
+  readonly sessionName?: string;
+}
+export interface SubagentCompletion {
+  readonly completionId?: string;
+  readonly runId: string;
+  readonly status: string;
+  readonly children: readonly {
+    readonly agent: string;
+    readonly index: number;
+    readonly status: string;
+    readonly intercomTarget: string;
+  }[];
+}
+export interface InboundMessageEntry {
+  readonly from: SessionInfo;
+  readonly message: Message;
+  readonly replyCommand?: string;
+  readonly bodyText: string;
+  readonly subagentCompletion?: SubagentCompletion & { readonly ownerSessionId: string };
+}
+export interface PendingInboundMessage extends InboundMessageEntry {
+  readonly flushDelivery: "auto" | "passive" | "steer";
+  readonly stage: "queued" | "native";
+  readonly receivedAt: number;
+}
+export type InboundCheckpoint =
+  | { readonly entry: PendingInboundMessage }
+  | {
+      readonly messageId: string;
+      readonly stage: PendingInboundMessage["stage"] | "discarded" | "reply-retired";
+    };
+export type RequestedDelivery = MessageDelivery | "auto";
+export type InboundDelivery = "trigger" | "followUp" | "steer" | "passive";
+export type ContactSupervisorReason = "need_decision" | "progress_update" | "interview_request";
+export type IntercomSessionScope = "project" | "all";
+export interface ToolResultLike {
+  readonly content: readonly { readonly type: "text"; readonly text: string }[];
+  readonly isError?: boolean;
+  readonly details?: Readonly<Record<string, unknown>>;
+}
+export interface ContactSupervisorToolParams {
+  readonly reason: ContactSupervisorReason;
+  readonly message?: string;
+  readonly interview?: unknown;
+}
+export interface IntercomToolParams {
+  readonly action:
+    | "list"
+    | "send"
+    | "ask"
+    | "reply"
+    | "pending"
+    | "status"
+    | "subscribe"
+    | "unsubscribe"
+    | "publish"
+    | "topics";
+  readonly scope?: IntercomSessionScope;
+  readonly to?: string;
+  readonly message?: string;
+  readonly attachments?: readonly Attachment[];
+  readonly replyTo?: string;
+  readonly delivery?: MessageDelivery;
+  readonly queueMode?: QueueMode;
+  readonly threadId?: string;
+  readonly passive?: boolean;
+  readonly topic?: string;
+  readonly event?: TopicUpdate["event"];
+  readonly resource?: string;
+  readonly ownership?: TopicUpdate["ownership"];
+  readonly awaitRelease?: boolean;
+}
+export type ToolRenderTheme = ExtensionContext["ui"]["theme"];
+export interface ToolRenderContext {
+  readonly args?: unknown;
+  readonly isError?: boolean;
+  readonly expanded?: boolean;
+}
+export const RECIPIENT_TURN_FAILED_ATTACHMENT = "pi-intercom-recipient-turn-failure";
+export const INBOUND_CHECKPOINT_TYPE = "intercom_delivery";
+export const TOPICS_UNAVAILABLE =
+  "Intercom topics are unavailable while an older broker is still running. Direct messaging and active sessions are unchanged. Let its sessions close normally; after it exits, reconnect with the updated package and retry. Nothing was stopped or restarted.";