@fitchmultz/pi-subagents 0.49.1 → 0.51.0

package/src/pi-intercom/index.ts

@@ -1,85 +1,55 @@
 import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
 import { loadConfig } from "./config.ts";
-import { readChildOrchestratorMetadata } from "./identity.ts";
+import { readIntercomLineage } from "./identity.ts";
 import { ReplyTracker } from "./reply-tracker.ts";
-import { IntercomTopics } from "./topics.ts";
 import { IntercomLifecycle } from "./lifecycle.ts";
 import { InboundJournal } from "./inbound-journal.ts";
 import { InboundDeliveryOwner } from "./inbound-delivery.ts";
 import { ReplyWait } from "./reply-wait.ts";
 import { IntercomConnection } from "./connection.ts";
 import { IntercomInbound } from "./inbound.ts";
-import { NativeControls } from "./native-control.ts";
 import { IntercomOutbound } from "./outbound.ts";
 import { IntercomInspection } from "./inspection.ts";
-import { IntercomTopicActions } from "./topic-actions.ts";
-import { IntercomSupervisor } from "./supervisor.ts";
 import { IntercomTools } from "./tools.ts";
-import { IntercomOverlay } from "./ui/overlay.ts";
-import { SubagentEventBridges } from "./subagent-events.ts";
 import { IntercomSessionEvents } from "./session-events.ts";
-import { PeerAwareness } from "./peer-awareness.ts";
-import { registerMessageRenderers } from "./ui/message-renderers.ts";
 import { registerIntercomTools } from "./tool-registration.ts";
 
 export default function piIntercomExtension(pi: ExtensionAPI): void {
   const config = loadConfig();
-  const child = readChildOrchestratorMetadata();
-  const lifecycle = new IntercomLifecycle(pi, config);
+  const lifecycle = new IntercomLifecycle(pi, config, readIntercomLineage());
   const replies = new ReplyTracker(config.askTimeoutMs);
-  const topics = new IntercomTopics(pi, () => lifecycle.live());
   const journal = new InboundJournal(pi, lifecycle, replies);
-  const wait = new ReplyWait(pi, lifecycle, config.askTimeoutMs);
-  // Hooks are invoked only after construction, at a native session or event boundary.
-  const connection = new IntercomConnection(lifecycle, config, topics, {
+  const wait = new ReplyWait(lifecycle, config.askTimeoutMs);
+  const connection = new IntercomConnection(lifecycle, config, {
     restoring: () => delivery.restoring,
     pendingAsks: () => replies.listPending().length,
-    incoming: async (ctx, from, message) => {
-      if (!(await controls.receive(ctx, from, message))) {
-        await inbound.receive(ctx, from, message);
-      }
-    },
+    receipt: (query) => journal.receipt(query),
+    incoming: (ctx, from, message) => inbound.receive(ctx, from, message),
     peerLeft: (id) => {
       wait.peerDisconnected(id);
       journal.peerLeft(id);
     },
     disconnected: (error) => {
-      if (!wait.durable) {
-        wait.reject(
-          new Error(`Disconnected while waiting for reply: ${error.message}`, { cause: error }),
-        );
-      }
+      wait.reject(
+        new Error(`Disconnected while waiting for reply: ${error.message}`, { cause: error }),
+      );
     },
   });
-  const controls = new NativeControls(lifecycle, connection);
   const delivery = new InboundDeliveryOwner(pi, lifecycle, journal, {
     replies,
     syncStatus: () => connection.syncStatus(),
   });
+  lifecycle.registerContextEvents(() => connection.syncStatus());
   const inbound = new IntercomInbound(lifecycle, config, {
-    journal,
     delivery,
+    journal,
     replies,
     wait,
     connection,
-    topics,
-    child,
   });
   const outbound = new IntercomOutbound({ pi, lifecycle, connection, replies, wait }, config);
   const inspection = new IntercomInspection(journal, replies);
-  const topicActions = new IntercomTopicActions({ pi, lifecycle, connection, topics });
-  const tools = new IntercomTools({ connection, outbound, topicActions, topics, inspection });
-  const supervisor = child
-    ? new IntercomSupervisor({ pi, lifecycle, connection, wait }, child)
-    : null;
-  const overlay = new IntercomOverlay({ pi, lifecycle, connection, topics });
-  const bridges = new SubagentEventBridges(lifecycle, connection, delivery, {
-    pi,
-    journal,
-    open: (ctx, scope) => overlay.open(ctx, scope),
-  });
-  const awareness = child ? null : new PeerAwareness(connection, lifecycle);
-  bridges.start();
+  const tools = new IntercomTools({ connection, outbound, inspection });
   new IntercomSessionEvents(pi, {
     lifecycle,
     connection,
@@ -87,12 +57,6 @@ export default function piIntercomExtension(pi: ExtensionAPI): void {
     journal,
     replies,
     wait,
-    topics,
-    bridges,
-    supervisor,
-    awareness,
   }).register();
-  registerMessageRenderers(pi);
-  registerIntercomTools(pi, tools, supervisor);
-  overlay.register(config.shortcut);
+  registerIntercomTools(pi, tools);
 }

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

@@ -0,0 +1,64 @@
+import type { ExtensionContext } from "@earendil-works/pi-coding-agent";
+import {
+  isLastMessageQuery,
+  LAST_MESSAGE_PAGE_LIMIT,
+  type LastMessageQuery,
+  type LastMessageResult,
+  type SessionInfo,
+} from "./types.ts";
+
+type NativeHistory = ExtensionContext["sessionManager"];
+function completedResponse(
+  manager: NativeHistory,
+  entryId?: string,
+): { readonly id: string; readonly text: string } | undefined {
+  for (const entry of manager.getBranch().reverse()) {
+    if (
+      entry.type === "message" &&
+      entry.message.role === "assistant" &&
+      (entry.message.stopReason === "stop" || entry.message.stopReason === "length") &&
+      (entryId === undefined || entry.id === entryId)
+    ) {
+      return {
+        id: entry.id,
+        text: entry.message.content
+          .filter((part) => part.type === "text")
+          .map((part) => part.text)
+          .join("\n"),
+      };
+    }
+  }
+  return;
+}
+/** Reads finalized native history only; no model invocation or synthesized response. */
+export function readLastMessage(
+  manager: NativeHistory,
+  session: SessionInfo,
+  query: LastMessageQuery,
+): LastMessageResult {
+  const offset = query.offset ?? 0;
+  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.",
+    };
+  }
+  const response = completedResponse(manager, query.entryId);
+  if (!response) {
+    return query.entryId !== undefined
+      ? { error: "Requested completed assistant response is not on the active session branch." }
+      : { session, entryId: null, text: "", offset: 0, totalLength: 0 };
+  }
+  if (offset > response.text.length) {
+    return { error: "Last response offset exceeds its length." };
+  }
+  const end = Math.min(response.text.length, offset + limit);
+  return {
+    session,
+    entryId: response.id,
+    text: response.text.slice(offset, end),
+    offset,
+    totalLength: response.text.length,
+    ...(end < response.text.length ? { nextOffset: end } : {}),
+  };
+}

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 } from "./identity.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 {
@@ -10,16 +30,21 @@ export class IntercomLifecycle {
   private sessionId: string | null = null;
   private model = "unknown";
   private disposed = true;
-  private started = false;
   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>();
   private readonly pi: ExtensionAPI;
   private readonly config: IntercomConfig;
-  constructor(pi: ExtensionAPI, config: IntercomConfig) {
+  private readonly lineage: IntercomLineage | undefined;
+  constructor(pi: ExtensionAPI, config: IntercomConfig, lineage?: IntercomLineage) {
     this.pi = pi;
     this.config = config;
+    this.lineage = lineage;
   }
   get generation(): number {
     return this.epoch;
@@ -27,22 +52,100 @@ export class IntercomLifecycle {
   get currentSessionId(): string | null {
     return this.sessionId;
   }
-  get runtimeStarted(): boolean {
-    return this.started;
-  }
   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.started = true;
     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 {
@@ -50,6 +153,7 @@ export class IntercomLifecycle {
     this.epoch += 1;
     this.running = false;
     this.tools.clear();
+    this.publishContext();
   }
   clear(): void {
     this.context = null;
@@ -76,22 +180,6 @@ export class IntercomLifecycle {
       return null;
     }
   }
-  notify(
-    ctx: ExtensionContext,
-    message: string,
-    level: "info" | "warning" | "error",
-    generation = this.epoch,
-  ): void {
-    const live = this.live(ctx, generation);
-    if (live?.hasUI !== true) {
-      return;
-    }
-    try {
-      live.ui.notify(message, level);
-    } catch {
-      // The UI may disappear while an asynchronous overlay settles during shutdown.
-    }
-  }
   isIdle(ctx: ExtensionContext): boolean {
     // ponytail: Pi 1.0 has no busy signal during foreign prompt preparation.
     if (this.running || this.tools.size > 0) {
@@ -123,8 +211,12 @@ export class IntercomLifecycle {
   markActivity(): void {
     this.activity = Date.now();
   }
-  identity(sessionId: string): { readonly name: string } {
-    return buildPresenceIdentity(this.pi, sessionId);
+  identity(sessionId: string): Pick<SessionInfo, "name" | "rootSessionId" | "parentSessionId"> {
+    return {
+      ...buildPresenceIdentity(this.pi, sessionId),
+      rootSessionId: this.lineage?.rootSessionId ?? sessionId,
+      parentSessionId: this.lineage?.parentSessionId,
+    };
   }
   status(): string {
     const tool = this.tools.values().next().value;
@@ -136,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,
@@ -153,31 +243,17 @@ 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),
     };
   }
-  targetMatches(to: string, resolvedTo?: string | null, brokerId?: string | null): boolean {
-    const targets = [
-      this.sessionId,
-      brokerId,
-      this.pi.getSessionName(),
-      this.sessionId === null ? undefined : this.identity(this.sessionId).name,
-    ];
-    return (
-      (resolvedTo !== undefined &&
-        resolvedTo !== null &&
-        brokerId !== undefined &&
-        brokerId !== null &&
-        resolvedTo === brokerId) ||
-      targets.some((target) => target?.trim().toLowerCase() === to.trim().toLowerCase())
-    );
-  }
 }

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

@@ -39,39 +39,6 @@ export function previewText(value: unknown, maxLength = 72): string | undefined
   }
   return normalized.length > maxLength ? `${normalized.slice(0, maxLength - 1)}…` : normalized;
 }
-function metadataField(text: string, pattern: Readonly<RegExp>): string | undefined {
-  return text.match(pattern)?.[1]?.trim();
-}
-function namedPreview(label: string, value: string | undefined): string | undefined {
-  return value === undefined || value === "" ? undefined : `${label}=${value}`;
-}
 export function pendingAskPreview(message: Message): string {
-  const text = message.content.text;
-  const normalized = text.replace(/\s+/g, " ").trim();
-  if (
-    !text.startsWith("Subagent needs a supervisor decision.") &&
-    !text.startsWith("Subagent requests a structured supervisor interview.")
-  ) {
-    return previewText(normalized, 180) ?? normalized;
-  }
-  const run = metadataField(text, /^Run:\s*(.+)$/m);
-  const agent = metadataField(text, /^Agent:\s*(.+)$/m);
-  const target = metadataField(text, /^Child intercom target:\s*(.+)$/m);
-  const body = text
-    .split(/\n\s*\n/)
-    .slice(1)
-    .join(" ")
-    .replace(/\s+/g, " ")
-    .trim();
-  return [
-    text.startsWith("Subagent requests")
-      ? "structured supervisor interview"
-      : "supervisor decision",
-    namedPreview("run", run),
-    namedPreview("agent", agent),
-    namedPreview("target", target),
-    namedPreview("question", previewText(body, 180)),
-  ]
-    .filter((part) => part !== undefined)
-    .join(" · ");
+  return previewText(message.content.text, 180) ?? message.content.text;
 }

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" },
@@ -284,10 +276,25 @@ export class IntercomOutbound {
     | { readonly target: string; readonly health: SessionInfo | null }
     | { readonly error: ToolResultLike }
   > {
-    const target = (await resolveConnectedTarget(active, to)) ?? to;
+    const target = await resolveConnectedTarget(active, to);
     if (this.isCancelled(signal)) {
       return { error: toolError("Cancelled") };
     }
+    if (target === null) {
+      return {
+        error: toolError(
+          `Ask to "${to}" was not sent: connected session not found.`,
+          failureDetails(
+            "delivery_failed",
+            [
+              { action: "list" },
+              { action: "send", guidance: "Retry with an exact active recipient target." },
+            ],
+            { accepted: false, delivered: false },
+          ),
+        ),
+      };
+    }
     if (target === active.sessionId) {
       return { error: toolError("Cannot message the current session") };
     }
@@ -394,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"
         ? [
@@ -408,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;
@@ -49,17 +50,13 @@ function pendingSenderOptions(
     .join(", ");
 }
 
-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);
+    throw new RecoveryError("ambiguous_reply_target", tooShort);
   }
   return resolveBySenderTarget(contexts, to);
 }
@@ -70,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 !== "" &&
@@ -86,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>();
@@ -155,8 +153,7 @@ 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;
     let expired = 0;
     for (const [messageId, context] of this.pendingAsks) {
       if (expires(context)) {
@@ -214,24 +211,15 @@ 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 {
     this.removeContext(replyTo);
   }
 
-  get hasReplyContext(): boolean {
-    return (
-      this.pendingAsks.size > 0 ||
-      this.pendingTurnContexts.length > 0 ||
-      this.currentTurnContext !== null ||
-      this.activeAgentContext !== null
-    );
-  }
-
   listPending(now = Date.now()): IntercomContext[] {
     this.pruneExpired(now);
     return Array.from(this.pendingAsks.values()).sort((a, b) => a.receivedAt - b.receivedAt);
@@ -262,10 +250,7 @@ export class ReplyTracker {
 
   private pruneExpired(now: number): void {
     for (const [messageId, context] of this.pendingAsks) {
-      if (
-        !isDurableSupervisorQuestion(context.message) &&
-        now - context.receivedAt > this.askTimeoutMs
-      ) {
+      if (now - context.receivedAt > this.askTimeoutMs) {
         this.removeContext(messageId);
       }
     }