@fitchmultz/pi-subagents 0.49.1 → 0.51.0

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

@@ -1,100 +1,14 @@
 import { StringEnum } from "@earendil-works/pi-ai";
-import { Type } from "../shared/native-typebox.ts";
-export const contactSupervisorSchema = Type.Object({
-  reason: StringEnum(["need_decision", "progress_update", "interview_request"] as const, {
-    description:
-      "Contact reason: 'need_decision' and 'interview_request' steer the supervisor and wait for a reply; 'progress_update' steers a material discovery without waiting for a reply",
-  }),
-  message: Type.Optional(
-    Type.String({
-      description:
-        "Decision request, optional interview note, or meaningful progress update for the supervisor",
-    }),
-  ),
-  interview: Type.Optional(
-    Type.Object(
-      {
-        title: Type.Optional(Type.String()),
-        description: Type.Optional(Type.String()),
-        questions: Type.Array(
-          Type.Object({
-            id: Type.String(),
-            type: StringEnum(["single", "multi", "text", "image", "info"] as const, {
-              description: "Question type: single, multi, text, image, or info",
-            }),
-            question: Type.String(),
-            options: Type.Optional(Type.Array(Type.Unknown())),
-            context: Type.Optional(Type.String()),
-          }),
-        ),
-      },
-      { description: "Structured interview request for reason='interview_request'" },
-    ),
-  ),
-});
+import { Type } from "../agent/typebox.ts";
 export const intercomSchema = Type.Object({
-  action: StringEnum(
-    [
-      "list",
-      "send",
-      "ask",
-      "reply",
-      "pending",
-      "status",
-      "subscribe",
-      "unsubscribe",
-      "publish",
-      "topics",
-    ] as const,
-    {
-      description:
-        "Direct messages: list/send/ask/reply/pending/status. Quiet state: subscribe/unsubscribe/publish/topics.",
-    },
-  ),
+  action: StringEnum(["list", "send", "ask", "reply", "pending", "status", "last"] as const),
   scope: Type.Optional(
     StringEnum(["project", "all"] as const, {
-      description:
-        "For list/status: 'project' (default) shows this Git repository and its worktrees; 'all' includes sessions in other projects.",
-    }),
-  ),
-  to: Type.Optional(
-    Type.String({
-      description: "Target session name or ID (for 'send', 'ask', or disambiguating 'reply')",
-    }),
-  ),
-  topic: Type.Optional(
-    Type.String({
-      description:
-        "Exact opt-in topic for subscribe/unsubscribe/publish/topics; no automatic subscriptions.",
-    }),
-  ),
-  event: Type.Optional(
-    StringEnum(["update", "blocker", "decision", "release"] as const, {
-      description:
-        "Publish: update is quiet current state. Blockers/decisions interrupt subscribers; release interrupts only those awaiting release.",
-    }),
-  ),
-  resource: Type.Optional(
-    Type.String({
-      description: "Publish: resource this session is using (advisory ownership, not a lock).",
-    }),
-  ),
-  ownership: Type.Optional(
-    StringEnum(["held", "released"] as const, {
-      description:
-        "Publish: this session's declared resource state. Disconnect never implies released.",
-    }),
-  ),
-  awaitRelease: Type.Optional(
-    Type.Boolean({
-      description: "Subscribe: interrupt when this topic explicitly releases ownership.",
-    }),
-  ),
-  message: Type.Optional(
-    Type.String({
-      description: "Message for send/ask/reply, or self-contained latest state for publish",
+      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({
@@ -105,30 +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'." }),
-  ),
-  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" })),
 });

package/src/pi-intercom/tools.ts

@@ -1,21 +1,38 @@
 import type { ExtensionContext } from "@earendil-works/pi-coding-agent";
 import type { IntercomTransport } from "./transport.ts";
-import type { IntercomConnection } from "./connection.ts";
+import { resolveConnectedTarget, type IntercomConnection } from "./connection.ts";
 import type { IntercomOutbound } from "./outbound.ts";
-import type { IntercomTopicActions } from "./topic-actions.ts";
-import type { IntercomTopics } from "./topics.ts";
 import type { IntercomInspection } from "./inspection.ts";
 import type { IntercomToolParams, ToolResultLike } from "./runtime-types.ts";
-import { validateIntercomArguments, toolError, toolText } from "./tool-arguments.ts";
+import { validateIntercomArguments, toolError } from "./tool-arguments.ts";
 import { errorMessage } from "./validation.ts";
-type Connection = Readonly<Pick<IntercomConnection, "ensure" | "syncIdentity">>;
-type TopicOwner = Readonly<Pick<IntercomTopics, "disconnected" | "inspect">>;
+import type { LastMessageResult } from "./types.ts";
+
+function lastPage(result: Exclude<LastMessageResult, { readonly error: string }>): ToolResultLike {
+  const identity = `${result.session.name ?? result.session.id} (${result.session.id})`;
+  const page =
+    result.entryId === null
+      ? "No completed assistant response."
+      : `Entry: ${result.entryId}\nCharacters (UTF-16): ${result.offset}–${result.offset + result.text.length} of ${result.totalLength}`;
+  const next =
+    result.nextOffset === undefined
+      ? ""
+      : `\nNext page: intercom(${JSON.stringify({ action: "last", to: result.session.id, entryId: result.entryId, offset: result.nextOffset })})`;
+  return {
+    content: [
+      { type: "text", text: result.text },
+      {
+        type: "text",
+        text: `Session: ${identity}\nStatus: ${result.session.status ?? "unknown"}\n${page}${next}`,
+      },
+    ],
+    details: { ...result },
+  };
+}
 
 interface ToolOwners {
-  readonly connection: Connection;
+  readonly connection: Readonly<Pick<IntercomConnection, "ensure" | "syncIdentity">>;
   readonly outbound: Readonly<Pick<IntercomOutbound, "send" | "ask" | "reply">>;
-  readonly topicActions: Readonly<Pick<IntercomTopicActions, "execute">>;
-  readonly topics: TopicOwner;
   readonly inspection: Readonly<Pick<IntercomInspection, "list" | "status" | "pending">>;
 }
 export class IntercomTools {
@@ -23,25 +40,49 @@ export class IntercomTools {
   constructor(owners: ToolOwners) {
     this.owners = owners;
   }
-  private async dispatch(
-    active: IntercomTransport,
+  async execute(
     params: IntercomToolParams,
     signal: AbortSignal | undefined,
     ctx: ExtensionContext,
   ): Promise<ToolResultLike> {
-    const scope = params.scope ?? "project";
+    const invalid = validateIntercomArguments(params);
+    if (invalid) {
+      return invalid;
+    }
+    let active: IntercomTransport;
+    try {
+      active = await this.owners.connection.ensure();
+    } catch (error) {
+      return toolError(`Intercom not connected: ${errorMessage(error)}`);
+    }
+    this.owners.connection.syncIdentity(ctx.sessionManager.getSessionId());
+    const scope = params.scope ?? "all";
     switch (params.action) {
-      case "subscribe":
-      case "unsubscribe":
-      case "publish":
-      case "topics":
-        return await this.owners.topicActions.execute(active, params, ctx);
       case "list":
         return await this.owners.inspection.list(active, scope);
       case "status":
         return await this.owners.inspection.status(active, scope, ctx);
       case "pending":
         return this.owners.inspection.pending();
+      case "last": {
+        if (params.to === undefined || params.to === "") {
+          return toolError("Missing 'to' parameter");
+        }
+        try {
+          const target = (await resolveConnectedTarget(active, params.to)) ?? params.to;
+          const result = await active.last(target, {
+            entryId: params.entryId,
+            offset: params.offset,
+            limit: params.limit,
+          });
+          if ("error" in result) {
+            return toolError(result.error);
+          }
+          return lastPage(result);
+        } catch (error) {
+          return toolError(`Failed to read last response: ${errorMessage(error)}`);
+        }
+      }
       case "send":
         return await this.owners.outbound.send(active, params, ctx);
       case "ask":
@@ -50,31 +91,4 @@ export class IntercomTools {
         return await this.owners.outbound.reply(active, params);
     }
   }
-  async execute(
-    params: IntercomToolParams,
-    signal: AbortSignal | undefined,
-    ctx: ExtensionContext,
-  ): Promise<ToolResultLike> {
-    let active: IntercomTransport;
-    try {
-      active = await this.owners.connection.ensure("tool");
-    } catch (error) {
-      if (params.action === "topics") {
-        this.owners.topics.disconnected();
-        return toolText(
-          `Broker unavailable; last saved records follow.\n${this.owners.topics.inspect(params.topic)}`,
-          { connection: "disconnected" },
-        );
-      }
-      return toolError(`Intercom not connected: ${errorMessage(error)}`);
-    }
-    this.owners.connection.syncIdentity(ctx.sessionManager.getSessionId());
-    if (!["subscribe", "unsubscribe", "publish", "topics"].includes(params.action)) {
-      const invalid = validateIntercomArguments(params);
-      if (invalid) {
-        return invalid;
-      }
-    }
-    return await this.dispatch(active, params, signal, ctx);
-  }
 }

package/src/pi-intercom/transport.ts

@@ -4,6 +4,7 @@ export type IntercomTransport = Readonly<
   Pick<
     IntercomClient,
     | "send"
+    | "last"
     | "isConnected"
     | "sessionId"
     | "supportsTopics"

package/src/pi-intercom/types.ts

@@ -2,13 +2,13 @@ import {
   finiteNumber,
   isRecord,
   isUnknownArray,
+  nonNegativeInteger,
   optionalBoolean,
   optionalFiniteNumber,
   optionalLabel,
   safeLabel,
   safeText,
 } from "./validation.ts";
-import type { NativeControlEnvelope } from "./native-control-protocol.ts";
 
 export interface SessionInfo {
   readonly id: string;
@@ -17,6 +17,11 @@ export interface SessionInfo {
   readonly model: string;
   /** Opaque same-repository/worktree identity used for ambient peer awareness. */
   readonly projectId?: string;
+  readonly rootSessionId?: string;
+  readonly parentSessionId?: string;
+  readonly incarnation?: string;
+  readonly guardedDelivery?: 1;
+  readonly applicationGuard?: string;
   readonly status?: string;
   readonly lastSeen?: number;
   readonly lastIntercomActivity?: number;
@@ -82,6 +87,42 @@ export function isTopicUpdate(value: unknown): value is TopicUpdate {
 
 export type MessageDelivery = "queue" | "steer" | "passive";
 export type QueueMode = "stack" | "replace";
+export interface ContextTarget {
+  readonly rootSessionId: string;
+  readonly peerId: string;
+  readonly incarnation: string;
+}
+export interface DeliveryGuard extends ContextTarget {
+  readonly applicationGuard: string;
+}
+export interface PublicationReplyHint {
+  readonly tool: string;
+  readonly commandId: string;
+  readonly commandFingerprint?: string;
+}
+export type SendOptions = Omit<Message, "id" | "timestamp" | "content"> &
+  Message["content"] & { readonly messageId?: string };
+export function isContextTarget(value: unknown): value is ContextTarget {
+  return (
+    isRecord(value) &&
+    ["rootSessionId", "peerId", "incarnation"].every((key) => safeLabel(value[key]))
+  );
+}
+export function isDeliveryGuard(value: unknown): value is DeliveryGuard {
+  return isContextTarget(value) && "applicationGuard" in value && safeLabel(value.applicationGuard);
+}
+export function isPublicationReplyHint(value: unknown): value is PublicationReplyHint {
+  return (
+    isRecord(value) &&
+    typeof value.tool === "string" &&
+    /^[a-zA-Z_][a-zA-Z0-9_]{0,79}$/.test(value.tool) &&
+    typeof value.commandId === "string" &&
+    /^[a-f0-9]{8}(?:-[a-f0-9]{4}){3}-[a-f0-9]{12}$/.test(value.commandId) &&
+    (value.commandFingerprint === undefined ||
+      (typeof value.commandFingerprint === "string" &&
+        /^[a-f0-9]{64}$/.test(value.commandFingerprint)))
+  );
+}
 export interface HumanMessageOrigin {
   readonly ownerSessionId: string;
   readonly runId: string;
@@ -107,7 +148,6 @@ export interface Message {
   readonly timestamp: number;
   readonly replyTo?: string;
   readonly expectsReply?: boolean;
-  readonly control?: NativeControlEnvelope;
   /** Recipients verify parent ownership before elevating human origin. */
   readonly human?: HumanMessageOrigin;
   readonly topic?: TopicUpdate;
@@ -115,6 +155,8 @@ export interface Message {
   readonly queueMode?: QueueMode;
   readonly threadId?: string;
   readonly passive?: boolean;
+  readonly guard?: DeliveryGuard;
+  readonly replyHint?: PublicationReplyHint;
   readonly content: {
     readonly text: string;
     readonly attachments?: readonly Attachment[];
@@ -137,6 +179,9 @@ export function isAttachment(value: unknown): value is Attachment {
 }
 
 function validMessageOrigin(message: Readonly<Record<string, unknown>>): boolean {
+  if (!validMessageGuard(message)) {
+    return false;
+  }
   if (message.human !== undefined && !isHumanMessageOrigin(message.human)) {
     return false;
   }
@@ -151,6 +196,20 @@ function validMessageOrigin(message: Readonly<Record<string, unknown>>): boolean
   );
 }
 
+function validMessageGuard(message: Readonly<Record<string, unknown>>): boolean {
+  if (message.guard === undefined) {
+    return message.replyHint === undefined;
+  }
+  return (
+    isDeliveryGuard(message.guard) &&
+    message.expectsReply === false &&
+    message.replyTo === undefined &&
+    message.human === undefined &&
+    message.topic === undefined &&
+    (message.replyHint === undefined || isPublicationReplyHint(message.replyHint))
+  );
+}
+
 function validDelivery(message: Readonly<Record<string, unknown>>): boolean {
   if (
     message.delivery !== undefined &&
@@ -252,17 +311,32 @@ function validSessionTopics(session: Readonly<Record<string, unknown>>): boolean
   );
 }
 
+function validSessionLineage(value: Readonly<Record<string, unknown>>): boolean {
+  return (
+    ["rootSessionId", "parentSessionId", "incarnation", "applicationGuard"].every((key) =>
+      optionalLabel(value[key]),
+    ) &&
+    (value.guardedDelivery === undefined ||
+      (value.guardedDelivery === 1 &&
+        safeLabel(value.incarnation) &&
+        safeLabel(value.rootSessionId))) &&
+    (value.parentSessionId === undefined || value.rootSessionId === value.parentSessionId)
+  );
+}
+
+function validSessionProject(value: unknown): boolean {
+  return value === undefined || (typeof value === "string" && /^[a-f0-9]{64}$/.test(value));
+}
+
 export function isSessionRegistration(value: unknown): value is Omit<SessionInfo, "id"> {
   if (!isRecord(value) || !safeLabel(value.cwd) || !safeLabel(value.model)) {
     return false;
   }
-  const validProject =
-    value.projectId === undefined ||
-    (typeof value.projectId === "string" && /^[a-f0-9]{64}$/.test(value.projectId));
   return (
     optionalLabel(value.name) &&
     optionalLabel(value.status) &&
-    validProject &&
+    validSessionLineage(value) &&
+    validSessionProject(value.projectId) &&
     validSessionHealth(value) &&
     validSessionTopics(value)
   );
@@ -345,12 +419,77 @@ export function normalizeMessage(value: unknown): Message | null {
   return isMessage(restored) ? restored : null;
 }
 
+export interface LastMessageQuery {
+  readonly entryId?: string;
+  readonly offset?: number;
+  readonly limit?: number;
+}
+
+export const LAST_MESSAGE_PAGE_LIMIT = 16384;
+function optionalEntryId(value: unknown): boolean {
+  return value === undefined || (typeof value === "string" && value.length > 0);
+}
+export function isLastMessageQuery(value: unknown): value is LastMessageQuery {
+  return (
+    isRecord(value) &&
+    value.messageId === undefined &&
+    optionalEntryId(value.entryId) &&
+    (value.offset === undefined || nonNegativeInteger(value.offset)) &&
+    (value.limit === undefined ||
+      (nonNegativeInteger(value.limit) &&
+        value.limit > 0 &&
+        value.limit <= LAST_MESSAGE_PAGE_LIMIT))
+  );
+}
+
+export type LastMessageResult =
+  | {
+      readonly session: SessionInfo;
+      readonly entryId: string | null;
+      readonly text: string;
+      readonly offset: number;
+      readonly totalLength: number;
+      readonly nextOffset?: number;
+    }
+  | { readonly error: string };
+
+export interface ReceiptQuery {
+  readonly rootSessionId: string;
+  readonly messageId: string;
+}
+export function isReceiptQuery(value: unknown): value is ReceiptQuery {
+  return isRecord(value) && [value.rootSessionId, value.messageId].every(safeLabel);
+}
+export interface NativeReceipt extends ReceiptQuery {
+  readonly version: 1;
+  readonly sender: {
+    readonly peerId: string;
+    readonly rootSessionId?: string;
+    readonly incarnation?: string;
+  };
+  readonly textSha256: string;
+  readonly delivery: MessageDelivery;
+  readonly guard?: DeliveryGuard;
+  readonly replyHint?: PublicationReplyHint;
+  readonly checkpointEntryId: string;
+  readonly receivedAt: number;
+  /** Historical observations, not a promise that an input is still queued. */
+  readonly queued: boolean;
+  readonly nativeHandoff: boolean;
+  readonly placementEntryId: string | null;
+  readonly discarded: boolean;
+}
+export type ReceiptResult = { readonly receipt: NativeReceipt } | { readonly error: string };
+
 export type BrokerMessage =
   | {
       readonly type: "registered";
       readonly sessionId: string;
       readonly topicsSupported?: true;
       readonly topicFrames?: true;
+      readonly lastMessages?: true;
+      readonly receiptReads?: 1;
+      readonly guardedDelivery?: 1;
     }
   | {
       readonly type: "sessions";
@@ -365,6 +504,17 @@ export type BrokerMessage =
       readonly from: SessionInfo;
       readonly message: Message | CompactTopicMessage;
     }
+  | {
+      readonly type: "last_request";
+      readonly requestId: string;
+      readonly from: SessionInfo;
+      readonly query: LastMessageQuery | ReceiptQuery;
+    }
+  | {
+      readonly type: "last_response";
+      readonly requestId: string;
+      readonly result: LastMessageResult | ReceiptResult;
+    }
   | { readonly type: "session_left"; readonly sessionId: string }
   | { readonly type: "delivered"; readonly messageId: string }
   | { readonly type: "delivery_queued"; readonly messageId: string; readonly reason: string }

package/src/pi-intercom/ui/session-format.ts

@@ -8,7 +8,7 @@ function shellQuote(value: string): string {
   return `'${value.replace(/'/g, `'\\''`)}'`;
 }
 function localForkStartCommand(): string {
-  return `pi --name worker --extension ${shellQuote(path.join(PACKAGE_ROOT, "src", "pi-intercom", "index.ts"))} --skill ${shellQuote(path.join(PACKAGE_ROOT, "skills", "pi-intercom"))}`;
+  return `pi --name worker --extension ${shellQuote(path.join(PACKAGE_ROOT, "src", "index.ts"))}`;
 }
 function duplicateNames(sessions: readonly SessionInfo[]): ReadonlySet<string> {
   const names = sessions
@@ -121,7 +121,7 @@ function noPeers(hidden: number): string {
 export function formatSessionListSections(
   allSessions: readonly SessionInfo[],
   id: string,
-  scope: IntercomSessionScope = "project",
+  scope: IntercomSessionScope = "all",
 ): string {
   const current = allSessions.find((session) => session.id === id);
   if (!current) {
@@ -140,7 +140,7 @@ export function formatSessionListSections(
   const otherSection = `**Other sessions:**\n${others.length === 0 ? noPeers(hidden) : others.map((session) => row(session, { ...options, self: false })).join("\n")}`;
   const hint =
     hidden > 0
-      ? `\n\n${hidden} session${hidden === 1 ? "" : "s"} in other projects hidden. Use \`intercom({ action: "list", scope: "all" })\` to show every connected session.`
+      ? `\n\n${hidden} session${hidden === 1 ? "" : "s"} in other projects hidden. Use \`intercom({ action: "list", scope: "all" })\` to show every reachable session.`
       : "";
   return `${currentSection}\n\n${otherSection}${hint}`;
 }

package/src/pi-intercom/validation.ts

@@ -64,6 +64,10 @@ export function finiteNumber(value: unknown): value is number {
   return typeof value === "number" && Number.isFinite(value);
 }
 
+export function nonNegativeInteger(value: unknown): value is number {
+  return typeof value === "number" && Number.isSafeInteger(value) && value >= 0;
+}
+
 export function optionalFiniteNumber(value: unknown): boolean {
   return value === undefined || finiteNumber(value);
 }