@fitchmultz/pi-subagents 0.50.0 → 0.52.0

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" })),
 });

package/src/pi-intercom/types.ts

@@ -2,6 +2,7 @@ import {
   finiteNumber,
   isRecord,
   isUnknownArray,
+  nonNegativeInteger,
   optionalBoolean,
   optionalFiniteNumber,
   optionalLabel,
@@ -18,6 +19,9 @@ export interface SessionInfo {
   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;
@@ -83,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;
@@ -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 &&
@@ -254,8 +313,13 @@ function validSessionTopics(session: Readonly<Record<string, unknown>>): boolean
 
 function validSessionLineage(value: Readonly<Record<string, unknown>>): boolean {
   return (
-    optionalLabel(value.rootSessionId) &&
-    optionalLabel(value.parentSessionId) &&
+    ["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)
   );
 }
@@ -361,6 +425,23 @@ export interface LastMessageQuery {
   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;
@@ -372,6 +453,34 @@ export type LastMessageResult =
     }
   | { 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";
@@ -379,6 +488,8 @@ export type BrokerMessage =
       readonly topicsSupported?: true;
       readonly topicFrames?: true;
       readonly lastMessages?: true;
+      readonly receiptReads?: 1;
+      readonly guardedDelivery?: 1;
     }
   | {
       readonly type: "sessions";
@@ -397,12 +508,12 @@ export type BrokerMessage =
       readonly type: "last_request";
       readonly requestId: string;
       readonly from: SessionInfo;
-      readonly query: LastMessageQuery;
+      readonly query: LastMessageQuery | ReceiptQuery;
     }
   | {
       readonly type: "last_response";
       readonly requestId: string;
-      readonly result: LastMessageResult;
+      readonly result: LastMessageResult | ReceiptResult;
     }
   | { readonly type: "session_left"; readonly sessionId: string }
   | { readonly type: "delivered"; readonly messageId: string }

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);
 }

package/src/shared/bounded-json.ts

@@ -0,0 +1,162 @@
+import { types } from "node:util";
+
+/** Live previews of arbitrary native values; durable journal records remain authoritative. */
+export type Unavailable = "oversize" | "cyclic" | "unreadable" | "unsupported";
+export type Bounded = { readonly json: string } | { readonly unavailable: Unavailable };
+export interface JsonBudget {
+  readonly bytes: number;
+  readonly nodes: number;
+  readonly depth: number;
+}
+class Limit extends Error {
+  readonly reason: Unavailable;
+  constructor(reason: Unavailable) {
+    super(reason);
+    this.reason = reason;
+  }
+}
+
+/**
+ * Proxies, accessors and custom serializers would run arbitrary code inside the actor; binary
+ * values allocate their full representation. None of them is read.
+ */
+function opaque(value: object): boolean {
+  return (
+    types.isProxy(value) ||
+    ArrayBuffer.isView(value) ||
+    types.isAnyArrayBuffer(value) ||
+    "toJSON" in value
+  );
+}
+/** An own data property's value, without invoking a getter. */
+function data(value: object, key: string): unknown {
+  const descriptor = Object.getOwnPropertyDescriptor(value, key);
+  if (descriptor !== undefined && !("value" in descriptor)) {
+    throw new Limit("unsupported");
+  }
+  return descriptor?.value;
+}
+
+/** Serialize like JSON.stringify within byte, node and depth limits, without first cloning. */
+class Writer {
+  private readonly parts: string[] = [];
+  private bytes = 0;
+  private nodes = 0;
+  private readonly ancestors = new Set<object>();
+  private readonly budget: JsonBudget;
+  constructor(budget: JsonBudget) {
+    this.budget = budget;
+  }
+  text(): string {
+    return this.parts.join("");
+  }
+  private add(text: string, bytes = text.length): void {
+    this.bytes += bytes;
+    if (this.bytes > this.budget.bytes) {
+      throw new Limit("oversize");
+    }
+    this.parts.push(text);
+  }
+  private string(value: string): void {
+    // A string never encodes to fewer bytes than code units; refuse before copying it.
+    if (value.length > this.budget.bytes - this.bytes) {
+      throw new Limit("oversize");
+    }
+    const json = JSON.stringify(value);
+    this.add(json, Buffer.byteLength(json));
+  }
+  /** Returns false for values JSON omits from objects and nulls in arrays. */
+  value(value: unknown, depth: number): boolean {
+    if (++this.nodes > this.budget.nodes) {
+      throw new Limit("oversize");
+    }
+    switch (typeof value) {
+      case "string":
+        this.string(value);
+        return true;
+      case "number":
+        this.add(Number.isFinite(value) ? String(value) : "null");
+        return true;
+      case "boolean":
+        this.add(String(value));
+        return true;
+      case "bigint":
+        throw new Limit("unsupported");
+      case "object":
+        this.object(value, depth);
+        return true;
+      case "undefined":
+      case "function":
+      case "symbol":
+        return false;
+    }
+  }
+  private object(value: object | null, depth: number): void {
+    if (value === null) {
+      this.add("null");
+      return;
+    }
+    if (depth >= this.budget.depth) {
+      throw new Limit("oversize");
+    }
+    if (this.ancestors.has(value)) {
+      throw new Limit("cyclic");
+    }
+    if (types.isDate(value) && !types.isProxy(value)) {
+      const time = Date.prototype.getTime.call(value);
+      this.add(Number.isNaN(time) ? "null" : JSON.stringify(new Date(time).toISOString()));
+      return;
+    }
+    if (opaque(value)) {
+      throw new Limit("unsupported");
+    }
+    this.ancestors.add(value);
+    if (Array.isArray(value)) {
+      this.array(value, depth + 1);
+    } else {
+      this.record(value, depth + 1);
+    }
+    this.ancestors.delete(value);
+  }
+  private array(value: readonly unknown[], depth: number): void {
+    this.add("[");
+    for (let index = 0; index < value.length; index++) {
+      if (index > 0) {
+        this.add(",");
+      }
+      if (!this.value(data(value, String(index)), depth)) {
+        this.add("null");
+      }
+    }
+    this.add("]");
+  }
+  private record(value: object, depth: number): void {
+    this.add("{");
+    let first = true;
+    for (const key of Object.keys(value)) {
+      const mark = { parts: this.parts.length, bytes: this.bytes };
+      if (!first) {
+        this.add(",");
+      }
+      this.string(key);
+      this.add(":");
+      if (this.value(data(value, key), depth)) {
+        first = false;
+      } else {
+        this.parts.length = mark.parts;
+        this.bytes = mark.bytes;
+      }
+    }
+    this.add("}");
+  }
+}
+
+export function boundedJson(value: unknown, budget: JsonBudget): Bounded {
+  const writer = new Writer(budget);
+  try {
+    return writer.value(value, 0) ? { json: writer.text() } : { unavailable: "unsupported" };
+  } catch (error) {
+    // Getters, proxies and revoked proxies are untrusted tool data, not observer failures.
+    return { unavailable: error instanceof Limit ? error.reason : "unreadable" };
+  }
+}

package/src/shared/compact-cards.ts

@@ -0,0 +1,118 @@
+import {
+  getMarkdownTheme,
+  keyHint,
+  truncateToVisualLines,
+  type ExtensionAPI,
+  type ExtensionContext,
+  type Theme,
+  type ToolDefinition,
+} from "@earendil-works/pi-coding-agent";
+import {
+  Box,
+  Container,
+  Markdown,
+  Spacer,
+  Text,
+  truncateToWidth,
+  type Component,
+} from "@earendil-works/pi-tui";
+import { actionText } from "./tui-action.ts";
+
+function preview(content: Component, expanded: boolean, theme: Theme, showHint = true): Component {
+  if (expanded) {
+    return content;
+  }
+  let cache: { width: number; lines: string[] } | undefined;
+  return {
+    render(width) {
+      if (cache?.width !== width) {
+        const { visualLines, skippedCount } = truncateToVisualLines(
+          content.render(width).join("\n"),
+          4,
+          width,
+          0,
+          "start",
+        );
+        const hint = theme.fg(
+          "dim",
+          `… ${skippedCount} more lines${showHint ? ` · ${keyHint("app.tools.expand", "to expand")}` : ""}`,
+        );
+        cache = {
+          width,
+          lines: skippedCount > 0 ? [...visualLines, truncateToWidth(hint, width)] : visualLines,
+        };
+      }
+      return cache.lines;
+    },
+    invalidate() {
+      cache = undefined;
+      content.invalidate();
+    },
+  };
+}
+
+export const renderCompactResult: NonNullable<ToolDefinition["renderResult"]> = (
+  result,
+  { expanded },
+  theme,
+) =>
+  preview(
+    new Text(
+      theme.fg(
+        "toolOutput",
+        result.content
+          .filter((block) => block.type === "text")
+          .map((block) => block.text)
+          .join("\n"),
+      ),
+      0,
+      0,
+    ),
+    expanded,
+    theme,
+  );
+
+export function registerCompactMessages(pi: ExtensionAPI, types: readonly string[]): void {
+  let ui: ExtensionContext["ui"] | undefined;
+  pi.on("session_start", (_event, ctx) => {
+    ui = ctx.mode === "tui" ? ctx.ui : undefined;
+  });
+  pi.on("session_shutdown", () => {
+    ui = undefined;
+  });
+  for (const type of types) {
+    pi.registerMessageRenderer(type, (message, { expanded, outputPad }, theme) => {
+      const text =
+        typeof message.content === "string"
+          ? message.content
+          : message.content
+              .filter((block) => block.type === "text")
+              .map((block) => block.text)
+              .join("\n");
+      const box = new Box(outputPad, 1, (line) => theme.bg("customMessageBg", line));
+      const markdown = new Markdown(text, 0, 0, getMarkdownTheme(), {
+        color: (line) => theme.fg("customMessageText", line),
+      });
+      box.addChild(
+        new (class extends Container {
+          override render(width: number): string[] {
+            this.clear();
+            const label = theme.fg("customMessageLabel", theme.bold(`[${type}]`));
+            this.addChild(
+              markdown.render(width).length > 4
+                ? actionText(
+                    `${label} · ${keyHint("app.tools.expand", expanded ? "to collapse" : "to expand")}`,
+                    () => ui?.setToolsExpanded(!expanded),
+                  )
+                : new Text(label, 0, 0),
+            );
+            return super.render(width);
+          }
+        })(),
+      );
+      box.addChild(new Spacer(1));
+      box.addChild(preview(markdown, expanded, theme, false));
+      return box;
+    });
+  }
+}

package/src/shared/journal-frames.ts

@@ -1,11 +1,5 @@
 import * as fs from "node:fs";
-import {
-  JsonProjection,
-  type Projection,
-  type ProjectionLimits,
-  type StringChunk,
-  type KeyLimit,
-} from "./json-projection.ts";
+import { JsonProjection, type Projection, type StringChunk } from "./json-projection.ts";
 import { errorDescription, isRecord, type UnknownRecord } from "./unknown.ts";
 
 export interface JournalRecord {
@@ -19,10 +13,7 @@ export interface JournalOptions {
   readonly requireNewline?: boolean;
   readonly start?: number;
   readonly end?: number;
-  readonly malformed?: (start: number, end: number, error: unknown) => void;
   readonly stringChunk?: StringChunk;
-  readonly keys?: KeyLimit;
-  readonly limits?: ProjectionLimits;
 }
 
 /** Byte-framed JSONL. Publication framing is independent of malformed-record tolerance. */
@@ -54,12 +45,7 @@ export class JournalFrames {
     this.projection = this.newProjection();
   }
   private newProjection(): JsonProjection {
-    return new JsonProjection(
-      this.select,
-      this.options.stringChunk,
-      this.options.keys,
-      this.options.limits,
-    );
+    return new JsonProjection(this.select, this.options.stringChunk);
   }
   private part(bytes: Buffer): void {
     if (!this.nonblank && bytes.some((byte) => ![9, 10, 13, 32].includes(byte))) {
@@ -107,9 +93,7 @@ export class JournalFrames {
     this.error = undefined;
     this.failed = false;
     this.nonblank = false;
-    if (failed) {
-      this.options.malformed?.(start, end, error);
-    } else if (record) {
+    if (!failed && record) {
       this.record(record);
     }
   }