@fitchmultz/pi-subagents 0.50.0 → 0.51.0

package/src/pi-intercom/last-message.ts

@@ -1,26 +1,18 @@
 import type { ExtensionContext } from "@earendil-works/pi-coding-agent";
-import type { LastMessageQuery, LastMessageResult, SessionInfo } from "./types.ts";
+import {
+  isLastMessageQuery,
+  LAST_MESSAGE_PAGE_LIMIT,
+  type LastMessageQuery,
+  type LastMessageResult,
+  type SessionInfo,
+} from "./types.ts";
 
 type NativeHistory = ExtensionContext["sessionManager"];
-function validPage(offset: number, limit: number): boolean {
-  return (
-    Number.isSafeInteger(offset) &&
-    offset >= 0 &&
-    Number.isSafeInteger(limit) &&
-    limit >= 1 &&
-    limit <= 16384
-  );
-}
 function completedResponse(
   manager: NativeHistory,
   entryId?: string,
 ): { readonly id: string; readonly text: string } | undefined {
-  let id = manager.getLeafId();
-  while (id !== null) {
-    const entry = manager.getEntry(id);
-    if (!entry) {
-      throw new Error("Native session history is unavailable.");
-    }
+  for (const entry of manager.getBranch().reverse()) {
     if (
       entry.type === "message" &&
       entry.message.role === "assistant" &&
@@ -35,7 +27,6 @@ function completedResponse(
           .join("\n"),
       };
     }
-    id = entry.parentId;
   }
   return;
 }
@@ -46,8 +37,8 @@ export function readLastMessage(
   query: LastMessageQuery,
 ): LastMessageResult {
   const offset = query.offset ?? 0;
-  const limit = query.limit ?? 16384;
-  if (!validPage(offset, limit)) {
+  const limit = query.limit ?? LAST_MESSAGE_PAGE_LIMIT;
+  if (!isLastMessageQuery({ offset, limit })) {
     return {
       error: "Invalid last response page: offset must be non-negative and limit must be 1–16384.",
     };

package/src/pi-intercom/lifecycle.ts

@@ -1,8 +1,28 @@
 import type { ExtensionAPI, ExtensionContext } from "@earendil-works/pi-coding-agent";
+import { randomUUID } from "node:crypto";
 import type { IntercomConfig } from "./config.ts";
 import { buildPresenceIdentity, type IntercomLineage } from "./identity.ts";
 import { resolveSessionProjectId } from "./session-targets.ts";
-import type { SessionInfo } from "./types.ts";
+import {
+  isContextTarget,
+  type ContextTarget,
+  type DeliveryGuard,
+  type SessionInfo,
+} from "./types.ts";
+import { isRecord, safeLabel } from "./validation.ts";
+
+export function isContextRequest(value: unknown): value is Readonly<Record<string, unknown>> & {
+  readonly respond: (response: unknown) => void;
+} {
+  return isRecord(value) && typeof value.respond === "function";
+}
+
+type ContextSnapshot = Readonly<Record<keyof ContextTarget, string | null>> &
+  Pick<SessionInfo, "parentSessionId" | "applicationGuard"> & {
+    readonly version: 1;
+    readonly connected: boolean;
+    readonly guardedDelivery: 1 | null;
+  };
 
 /** Owns native context validity and occupancy, never journal or socket state. */
 export class IntercomLifecycle {
@@ -11,6 +31,10 @@ export class IntercomLifecycle {
   private model = "unknown";
   private disposed = true;
   private epoch = 0;
+  private incarnation: string | null = null;
+  private peerId: string | null = null;
+  private guardedDelivery = false;
+  private applicationGuard: string | undefined;
   private running = false;
   private activity = 0;
   private readonly tools = new Map<string, string>();
@@ -31,15 +55,97 @@ export class IntercomLifecycle {
   get toolCount(): number {
     return this.tools.size;
   }
+  registerContextEvents(sync: () => void): void {
+    this.pi.events.on("pi-intercom:context-query", (request) => this.contextRequest(request));
+    this.pi.events.on("pi-intercom:application-guard", (request) =>
+      this.contextRequest(request, sync),
+    );
+  }
+  private contextRequest(request: unknown, sync?: () => void): void {
+    if (!isContextRequest(request)) {
+      return;
+    }
+    if (request.version !== 1) {
+      request.respond({ error: "unsupported_version" });
+      return;
+    }
+    if (sync) {
+      if (
+        !isContextTarget(request.target) ||
+        !this.matches(request.target) ||
+        !(
+          request.revision === null ||
+          (typeof request.revision === "string" && safeLabel(request.revision))
+        )
+      ) {
+        request.respond({ error: "context_changed" });
+        return;
+      }
+      this.applicationGuard = request.revision === null ? undefined : request.revision;
+      sync();
+      this.publishContext();
+    }
+    request.respond(this.snapshot());
+  }
+  snapshot(): ContextSnapshot {
+    if (!this.live()) {
+      return {
+        version: 1,
+        rootSessionId: null,
+        peerId: null,
+        incarnation: null,
+        connected: false,
+        guardedDelivery: null,
+      } as const;
+    }
+    return {
+      version: 1,
+      rootSessionId: this.lineage?.rootSessionId ?? this.sessionId,
+      parentSessionId: this.lineage?.parentSessionId,
+      peerId: this.peerId,
+      incarnation: this.incarnation,
+      connected: this.peerId !== null,
+      guardedDelivery: this.guardedDelivery ? 1 : null,
+      applicationGuard: this.applicationGuard,
+    } as const;
+  }
+  private publishContext(): void {
+    this.pi.events.emit("pi-intercom:context-state", this.snapshot());
+  }
+  transport(peerId: string | null, guardedDelivery = false): void {
+    this.peerId = peerId;
+    this.guardedDelivery = guardedDelivery;
+    this.publishContext();
+  }
+  private matches(target: ContextTarget): boolean {
+    const current = this.snapshot();
+    return (
+      current.connected &&
+      current.rootSessionId === target.rootSessionId &&
+      current.peerId === target.peerId &&
+      current.incarnation === target.incarnation
+    );
+  }
+  accepts(guard: DeliveryGuard): boolean {
+    return (
+      this.guardedDelivery &&
+      this.lineage?.parentSessionId === undefined &&
+      this.matches(guard) &&
+      this.applicationGuard === guard.applicationGuard
+    );
+  }
   start(ctx: ExtensionContext): number {
     this.disposed = false;
     this.epoch += 1;
     this.context = ctx;
     this.sessionId = ctx.sessionManager.getSessionId();
+    this.incarnation = randomUUID();
+    this.applicationGuard = undefined;
     this.model = ctx.model?.id ?? "unknown";
     this.running = false;
     this.activity = 0;
     this.tools.clear();
+    this.transport(null);
     return this.epoch;
   }
   invalidate(): void {
@@ -47,6 +153,7 @@ export class IntercomLifecycle {
     this.epoch += 1;
     this.running = false;
     this.tools.clear();
+    this.publishContext();
   }
   clear(): void {
     this.context = null;
@@ -104,11 +211,7 @@ export class IntercomLifecycle {
   markActivity(): void {
     this.activity = Date.now();
   }
-  identity(sessionId: string): {
-    readonly name: string;
-    readonly rootSessionId: string;
-    readonly parentSessionId?: string;
-  } {
+  identity(sessionId: string): Pick<SessionInfo, "name" | "rootSessionId" | "parentSessionId"> {
     return {
       ...buildPresenceIdentity(this.pi, sessionId),
       rootSessionId: this.lineage?.rootSessionId ?? sessionId,
@@ -125,11 +228,9 @@ export class IntercomLifecycle {
       ? `${status} · ${this.config.status}`
       : status;
   }
-  health(pendingAsks: number): {
-    readonly pendingAsks: number;
-    readonly acceptsAsks: boolean;
-    readonly lastIntercomActivity: number;
-  } {
+  health(
+    pendingAsks: number,
+  ): Pick<SessionInfo, "pendingAsks" | "acceptsAsks" | "lastIntercomActivity"> {
     const live = this.live();
     return {
       pendingAsks,
@@ -142,12 +243,14 @@ export class IntercomLifecycle {
     if (!live || this.sessionId === null) {
       throw new Error("Intercom runtime not initialized");
     }
-    const cwd = live.cwd;
     return {
       ...this.identity(this.sessionId),
-      cwd,
+      incarnation: this.incarnation ?? undefined,
+      guardedDelivery: 1,
+      applicationGuard: this.applicationGuard,
+      cwd: live.cwd,
       model: this.model,
-      projectId: await resolveSessionProjectId(cwd),
+      projectId: await resolveSessionProjectId(live.cwd),
       lastSeen: Date.now(),
       status: this.status(),
       ...this.health(pendingAsks),

package/src/pi-intercom/outbound.ts

@@ -22,7 +22,7 @@ import { formatAttachments } from "./message-format.ts";
 import {
   AskDeliveryError,
   failureDetails,
-  replyFailureReason,
+  RecoveryError,
   type RecoveryAction,
 } from "./tool-results.ts";
 import { sendOptions, toolError, toolText } from "./tool-arguments.ts";
@@ -155,11 +155,10 @@ export class IntercomOutbound {
       }
       return this.sent(to, params, result);
     } catch (error) {
-      const text = errorMessage(error);
       return toolError(
-        `Failed to send: ${text}`,
+        `Failed to send: ${errorMessage(error)}`,
         failureDetails(
-          text.startsWith("Target ") ? "ambiguous_target" : "send_failed",
+          error instanceof RecoveryError ? error.code : "send_failed",
           [
             { action: "list" },
             { action: "send", guidance: "Retry with an exact active recipient target." },
@@ -225,17 +224,10 @@ export class IntercomOutbound {
       const result = this.deliveryFailure(to, error.result);
       return { ...result, details: { ...result.details, error: true } };
     }
-    const text = errorMessage(error);
-    let reason = "ask_failed";
-    if (text.startsWith("No reply from")) {
-      reason = "reply_timeout";
-    } else if (text.startsWith("Target ")) {
-      reason = "ambiguous_target";
-    }
     return toolError(
-      `Failed: ${text}`,
+      `Failed: ${errorMessage(error)}`,
       failureDetails(
-        reason,
+        error instanceof RecoveryError ? error.code : "ask_failed",
         [
           { action: "status" },
           { action: "list" },
@@ -409,8 +401,7 @@ export class IntercomOutbound {
     }
   }
   private replyFailure(error: unknown, replyTo: string | undefined): ToolResultLike {
-    const text = errorMessage(error);
-    const reason = replyFailureReason(text);
+    const reason = error instanceof RecoveryError ? error.code : "reply_failed";
     const actions: readonly RecoveryAction[] =
       reason === "no_pending_reply"
         ? [
@@ -423,7 +414,7 @@ export class IntercomOutbound {
           ]
         : [{ action: "pending" }, { action: "list" }];
     return toolError(
-      `Failed to reply: ${text}`,
+      `Failed to reply: ${errorMessage(error)}`,
       failureDetails(reason, actions, {
         error: true,
         ...((replyTo ?? "") !== "" ? { replyTo } : {}),

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

@@ -1,5 +1,6 @@
 import type { Message, SessionInfo } from "./types.ts";
 import { formatSessionTarget, resolveSessionTarget, shortSessionId } from "./session-targets.ts";
+import { RecoveryError } from "./tool-results.ts";
 
 export interface IntercomContext {
   readonly from: SessionInfo;
@@ -55,7 +56,7 @@ function matchingSender(
 ): readonly IntercomContext[] {
   const tooShort = tooShortSenderTargetMessage(contexts, to);
   if (tooShort !== null && tooShort !== "") {
-    throw new Error(tooShort);
+    throw new RecoveryError("ambiguous_reply_target", tooShort);
   }
   return resolveBySenderTarget(contexts, to);
 }
@@ -66,7 +67,7 @@ function explicitReply(
 ): IntercomContext {
   const target = contexts.find((context) => context.message.id === replyTo);
   if (!target) {
-    throw new Error(`No pending ask with replyTo "${replyTo}"`);
+    throw new RecoveryError("no_pending_reply", `No pending ask with replyTo "${replyTo}"`);
   }
   if (
     to !== "" &&
@@ -82,11 +83,12 @@ function replyBySender(contexts: readonly IntercomContext[], to: string): Interc
     return matches[0];
   }
   if (matches.length > 1) {
-    throw new Error(
+    throw new RecoveryError(
+      "ambiguous_reply_target",
       `Multiple pending asks from "${to}" — use one of: ${pendingSenderOptions(matches, contexts)}.`,
     );
   }
-  throw new Error(`No pending ask from "${to}"`);
+  throw new RecoveryError("no_pending_reply", `No pending ask from "${to}"`);
 }
 export class ReplyTracker {
   private readonly pendingAsks = new Map<string, IntercomContext>();
@@ -209,9 +211,9 @@ export class ReplyTracker {
       return pending[0];
     }
     if (pending.length === 0) {
-      throw new Error("No active intercom context to reply to");
+      throw new RecoveryError("no_pending_reply", "No active intercom context to reply to");
     }
-    throw new Error("Multiple pending asks — specify `to`");
+    throw new RecoveryError("ambiguous_reply_target", "Multiple pending asks — specify `to`");
   }
 
   markReplied(replyTo: string): void {

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

@@ -3,7 +3,7 @@ import type { IntercomClient, SendResult } from "./broker/client.ts";
 import type { IntercomTransport } from "./transport.ts";
 import type { IntercomLifecycle } from "./lifecycle.ts";
 import { asError } from "./validation.ts";
-import { AskDeliveryError } from "./tool-results.ts";
+import { AskDeliveryError, RecoveryError } from "./tool-results.ts";
 
 type Lifecycle = Readonly<Pick<IntercomLifecycle, "markActivity">>;
 interface ReplyWaiter {
@@ -71,7 +71,8 @@ export class ReplyWait {
       const { from, replyTo, signal } = options;
       const timeout = setTimeout(() => {
         this.reject(
-          new Error(
+          new RecoveryError(
+            "reply_timeout",
             `No reply from "${from}" within ${Math.max(1, Math.round(this.timeoutMs / 60000))} minute(s)`,
           ),
         );

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

@@ -17,7 +17,6 @@ export type InboundCheckpoint =
       readonly messageId: string;
       readonly stage: PendingInboundMessage["stage"] | "discarded" | "reply-retired";
     };
-export type RequestedDelivery = MessageDelivery | "auto";
 export type InboundDelivery = "trigger" | "followUp" | "steer" | "passive";
 export type IntercomSessionScope = "project" | "all";
 export interface ToolResultLike {

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

@@ -2,17 +2,20 @@ import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
 import type { IntercomTools } from "./tools.ts";
 import { throwIfToolError } from "./tool-results.ts";
 import { intercomSchema } from "./tool-schemas.ts";
+import { registerCompactMessages, renderCompactResult } from "../shared/compact-cards.ts";
 
 export function registerIntercomTools(
   pi: ExtensionAPI,
   tools: Readonly<Pick<IntercomTools, "execute">>,
 ): void {
+  registerCompactMessages(pi, ["intercom_message", "subagent-human-message"]);
   pi.registerTool({
     name: "intercom",
     label: "Intercom",
     description:
-      "Discover and message connected Pi sessions in your collaboration group; main sessions can also reach other mains, across projects. Use list for unambiguous targets. Send defaults to steer at the next tool boundary; queue defers; passive never wakes the model. Ask waits for a correlated reply; reply answers the active or single pending ask (specify replyTo when ambiguous). Pending lists asks; status shows connection and inbound queue state. Last reads a peer's original completed assistant response without waking it; page using entryId and nextOffset. Broker acceptance is not recipient persistence, consumption, or task completion.",
+      "Message connected Pi sessions in your group; mains also reach other mains across projects. List shows target IDs. Ask waits for a correlated reply; reply answers the active or sole pending ask. Pending lists asks; status shows connection and inbound queue. Last pages a peer's last completed response without waking it. Broker acceptance is not recipient persistence, consumption or completion.",
     parameters: intercomSchema,
+    renderResult: renderCompactResult,
     async execute(_id, params, signal, _update, ctx) {
       const result = throwIfToolError(await tools.execute(params, signal, ctx));
       return { content: [...result.content], details: result.details };

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

@@ -1,5 +1,10 @@
 import type { SendResult } from "./types.ts";
 import type { ToolResultLike } from "./runtime-types.ts";
+type RecoveryCode =
+  | "ambiguous_target"
+  | "reply_timeout"
+  | "no_pending_reply"
+  | "ambiguous_reply_target";
 export interface RecoveryAction {
   readonly action: "list" | "pending" | "send" | "status";
   readonly guidance?: string;
@@ -11,16 +16,12 @@ export function failureDetails(
 ): 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";
+export class RecoveryError extends Error {
+  readonly code: RecoveryCode;
+  constructor(code: RecoveryCode, message: string) {
+    super(message);
+    this.code = code;
   }
-  return "reply_failed";
 }
 export function firstTextContent(result: {
   readonly content?: readonly { readonly type: string; readonly text?: string }[];

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

@@ -1,26 +1,14 @@
 import { StringEnum } from "@earendil-works/pi-ai";
 import { Type } from "../agent/typebox.ts";
 export const intercomSchema = Type.Object({
-  action: StringEnum(["list", "send", "ask", "reply", "pending", "status", "last"] as const, {
-    description:
-      "List, send, ask, reply, pending asks, connection status, or last completed assistant response.",
-  }),
+  action: StringEnum(["list", "send", "ask", "reply", "pending", "status", "last"] as const),
   scope: Type.Optional(
     StringEnum(["project", "all"] as const, {
-      description:
-        "For list/status: 'all' (default) includes every reachable session; 'project' further filters this repository and its worktrees.",
-    }),
-  ),
-  to: Type.Optional(
-    Type.String({
-      description: "Target session name or ID (for 'send', 'ask', or disambiguating 'reply')",
-    }),
-  ),
-  message: Type.Optional(
-    Type.String({
-      description: "Message for send/ask/reply",
+      description: "all (default) or project (repo and worktrees)",
     }),
   ),
+  to: Type.Optional(Type.String({ description: "Session name or ID" })),
+  message: Type.Optional(Type.String()),
   attachments: Type.Optional(
     Type.Array(
       Type.Object({
@@ -31,41 +19,21 @@ export const intercomSchema = Type.Object({
       }),
     ),
   ),
-  replyTo: Type.Optional(
-    Type.String({
-      description: "Message ID to reply to (for threading or responding to an 'ask')",
-    }),
-  ),
+  replyTo: Type.Optional(Type.String({ description: "Message ID to answer or thread" })),
   delivery: Type.Optional(
     StringEnum(["queue", "steer", "passive"] as const, {
       description:
-        "Delivery mode. Omitted send delivery defaults to 'steer', which injects after the current tool call. Use 'queue' only to intentionally wait behind active work; 'passive' does not wake the recipient model.",
+        "steer (default) at next tool boundary; queue after active work; passive never wakes the model",
     }),
   ),
   queueMode: Type.Optional(
     StringEnum(["stack", "replace"] as const, {
-      description:
-        "For delivery='queue': 'stack' keeps all messages; 'replace' keeps only the latest undelivered message for the same threadId.",
-    }),
-  ),
-  threadId: Type.Optional(
-    Type.String({ description: "Stable topic key for queueMode='replace'." }),
-  ),
-  entryId: Type.Optional(Type.String({ description: "Last response entry ID for stable paging." })),
-  offset: Type.Optional(
-    Type.Integer({ minimum: 0, description: "Last response character offset (UTF-16)." }),
-  ),
-  limit: Type.Optional(
-    Type.Integer({
-      minimum: 1,
-      maximum: 16384,
-      description: "Last response page size; default/max 16384 characters.",
-    }),
-  ),
-  passive: Type.Optional(
-    Type.Boolean({
-      description:
-        "For action='send' only: legacy alias for delivery='passive'. Discouraged for agent-to-agent messages.",
+      description: "stack keeps all; replace keeps only the latest per threadId",
     }),
   ),
+  threadId: Type.Optional(Type.String()),
+  entryId: Type.Optional(Type.String()),
+  offset: Type.Optional(Type.Integer({ minimum: 0, description: "UTF-16 characters" })),
+  limit: Type.Optional(Type.Integer({ minimum: 1, maximum: 16384 })),
+  passive: Type.Optional(Type.Boolean({ description: "Legacy alias for delivery=passive" })),
 });