@fitchmultz/pi-subagents 0.50.0 → 0.51.0

package/dist/pi-intercom/tool-schemas.js

@@ -1,42 +1,28 @@
 import { StringEnum } from "@earendil-works/pi-ai";
 import { Type } from "../agent/typebox.js";
 export const intercomSchema = Type.Object({
-    action: StringEnum(["list", "send", "ask", "reply", "pending", "status", "last"], {
-        description: "List, send, ask, reply, pending asks, connection status, or last completed assistant response.",
-    }),
+    action: StringEnum(["list", "send", "ask", "reply", "pending", "status", "last"]),
     scope: Type.Optional(StringEnum(["project", "all"], {
-        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({
         type: StringEnum(["file", "snippet", "context"]),
         name: Type.String(),
         content: Type.String(),
         language: Type.Optional(Type.String()),
     }))),
-    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"], {
-        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.",
+        description: "steer (default) at next tool boundary; queue after active work; passive never wakes the model",
     })),
     queueMode: Type.Optional(StringEnum(["stack", "replace"], {
-        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/dist/pi-intercom/types.d.ts

@@ -0,0 +1,212 @@
+export interface SessionInfo {
+    readonly id: string;
+    readonly name?: string;
+    readonly cwd: string;
+    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;
+    readonly pendingAsks?: number;
+    readonly acceptsAsks?: boolean;
+    readonly subscriptions?: readonly TopicSubscription[];
+    readonly topics?: readonly TopicUpdate[];
+}
+export interface TopicSubscription {
+    readonly topic: string;
+    readonly awaitRelease?: boolean;
+}
+export interface TopicUpdate {
+    readonly topic: string;
+    readonly text: string;
+    readonly event: "update" | "blocker" | "decision" | "release";
+    readonly resource?: string;
+    readonly ownership?: "held" | "released";
+    readonly revision: number;
+    readonly updatedAt: number;
+}
+export declare function isTopicSubscription(value: unknown): value is TopicSubscription;
+export declare 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 declare function isContextTarget(value: unknown): value is ContextTarget;
+export declare function isDeliveryGuard(value: unknown): value is DeliveryGuard;
+export declare function isPublicationReplyHint(value: unknown): value is PublicationReplyHint;
+export interface HumanMessageOrigin {
+    readonly ownerSessionId: string;
+    readonly runId: string;
+    readonly index: number;
+}
+export declare function isHumanMessageOrigin(value: unknown): value is HumanMessageOrigin;
+export interface Message {
+    readonly id: string;
+    readonly timestamp: number;
+    readonly replyTo?: string;
+    readonly expectsReply?: boolean;
+    /** Recipients verify parent ownership before elevating human origin. */
+    readonly human?: HumanMessageOrigin;
+    readonly topic?: TopicUpdate;
+    readonly delivery?: MessageDelivery;
+    readonly queueMode?: QueueMode;
+    readonly threadId?: string;
+    readonly passive?: boolean;
+    readonly guard?: DeliveryGuard;
+    readonly replyHint?: PublicationReplyHint;
+    readonly content: {
+        readonly text: string;
+        readonly attachments?: readonly Attachment[];
+    };
+}
+export interface Attachment {
+    readonly type: "file" | "snippet" | "context";
+    readonly name: string;
+    readonly content: string;
+    readonly language?: string;
+}
+export declare function isAttachment(value: unknown): value is Attachment;
+export declare function isMessage(value: unknown): value is Message;
+export declare function isSessionRegistration(value: unknown): value is Omit<SessionInfo, "id">;
+export declare function normalizeSessionInfo(value: unknown): SessionInfo | null;
+export interface SendResult {
+    readonly id: string;
+    readonly accepted: boolean;
+    readonly delivered: boolean;
+    readonly queued?: boolean;
+    readonly reason?: string;
+}
+export type TopicChange = {
+    readonly action: "publish" | "restore";
+    readonly topic: TopicUpdate;
+} | {
+    readonly action: "subscribe" | "restore";
+    readonly subscription: TopicSubscription;
+} | {
+    readonly action: "unsubscribe";
+    readonly topic: string;
+};
+export interface SessionSnapshot {
+    readonly sessions: readonly SessionInfo[];
+    readonly receipts: readonly (SendResult & {
+        readonly to: string;
+    })[];
+}
+type CompactTopicMessage = Omit<Message, "topic"> & {
+    readonly topic?: Omit<TopicUpdate, "text"> & {
+        readonly text?: string;
+    };
+};
+/** Topic text and the standard coalescing key need only one copy on the wire. */
+export declare function compactTopicMessage(message: Message): CompactTopicMessage;
+export declare function normalizeMessage(value: unknown): Message | null;
+export interface LastMessageQuery {
+    readonly entryId?: string;
+    readonly offset?: number;
+    readonly limit?: number;
+}
+export declare const LAST_MESSAGE_PAGE_LIMIT = 16384;
+export declare function isLastMessageQuery(value: unknown): value is LastMessageQuery;
+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 declare function isReceiptQuery(value: unknown): value is ReceiptQuery;
+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";
+    readonly requestId: string;
+    readonly sessions: readonly (Partial<SessionInfo> & Pick<SessionInfo, "id">)[];
+    readonly more?: boolean;
+    readonly receipts?: SessionSnapshot["receipts"];
+    readonly error?: string;
+} | {
+    readonly type: "message";
+    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;
+} | {
+    readonly type: "delivery_failed";
+    readonly messageId: string;
+    readonly reason: string;
+};
+export {};

package/dist/pi-intercom/types.js

@@ -1,4 +1,4 @@
-import { finiteNumber, isRecord, isUnknownArray, optionalBoolean, optionalFiniteNumber, optionalLabel, safeLabel, safeText, } from "./validation.js";
+import { finiteNumber, isRecord, isUnknownArray, nonNegativeInteger, optionalBoolean, optionalFiniteNumber, optionalLabel, safeLabel, safeText, } from "./validation.js";
 export function isTopicSubscription(value) {
     return (isRecord(value) &&
         typeof value.topic === "string" &&
@@ -30,6 +30,23 @@ export function isTopicUpdate(value) {
         finiteNumber(value.updatedAt) &&
         validTopicOwnership(value));
 }
+export function isContextTarget(value) {
+    return (isRecord(value) &&
+        ["rootSessionId", "peerId", "incarnation"].every((key) => safeLabel(value[key])));
+}
+export function isDeliveryGuard(value) {
+    return isContextTarget(value) && "applicationGuard" in value && safeLabel(value.applicationGuard);
+}
+export function isPublicationReplyHint(value) {
+    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 function isHumanMessageOrigin(value) {
     if (!isRecord(value)) {
         return false;
@@ -50,6 +67,9 @@ export function isAttachment(value) {
     return (validType && safeLabel(value.name) && safeText(value.content) && optionalLabel(value.language));
 }
 function validMessageOrigin(message) {
+    if (!validMessageGuard(message)) {
+        return false;
+    }
     if (message.human !== undefined && !isHumanMessageOrigin(message.human)) {
         return false;
     }
@@ -61,6 +81,17 @@ function validMessageOrigin(message) {
         (message.expectsReply === undefined || message.expectsReply === false) &&
         message.replyTo === undefined);
 }
+function validMessageGuard(message) {
+    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) {
     if (message.delivery !== undefined &&
         message.delivery !== "queue" &&
@@ -136,8 +167,11 @@ function validSessionTopics(session) {
             (isUnknownArray(session.topics) && session.topics.every(isTopicUpdate))));
 }
 function validSessionLineage(value) {
-    return (optionalLabel(value.rootSessionId) &&
-        optionalLabel(value.parentSessionId) &&
+    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) {
@@ -205,3 +239,20 @@ export function normalizeMessage(value) {
     };
     return isMessage(restored) ? restored : null;
 }
+export const LAST_MESSAGE_PAGE_LIMIT = 16384;
+function optionalEntryId(value) {
+    return value === undefined || (typeof value === "string" && value.length > 0);
+}
+export function isLastMessageQuery(value) {
+    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 function isReceiptQuery(value) {
+    return isRecord(value) && [value.rootSessionId, value.messageId].every(safeLabel);
+}

package/dist/pi-intercom/validation.d.ts

@@ -0,0 +1,12 @@
+/** JSON objects are untrusted at the broker and journal boundaries. */
+export declare function isRecord(value: unknown): value is Readonly<Record<string, unknown>>;
+export declare function isUnknownArray(value: unknown): value is readonly unknown[];
+export declare function errorMessage(error: unknown): string;
+export declare function asError(error: unknown): Error;
+export declare function safeText(value: unknown): boolean;
+export declare function safeLabel(value: unknown): boolean;
+export declare function optionalLabel(value: unknown): boolean;
+export declare function optionalBoolean(value: unknown): boolean;
+export declare function finiteNumber(value: unknown): value is number;
+export declare function nonNegativeInteger(value: unknown): value is number;
+export declare function optionalFiniteNumber(value: unknown): boolean;

package/dist/pi-intercom/validation.js

@@ -54,6 +54,9 @@ export function optionalBoolean(value) {
 export function finiteNumber(value) {
     return typeof value === "number" && Number.isFinite(value);
 }
+export function nonNegativeInteger(value) {
+    return typeof value === "number" && Number.isSafeInteger(value) && value >= 0;
+}
 export function optionalFiniteNumber(value) {
     return value === undefined || finiteNumber(value);
 }

package/dist/shared/bounded-json.js

@@ -0,0 +1,151 @@
+import { types } from "node:util";
+class Limit extends Error {
+    reason;
+    constructor(reason) {
+        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) {
+    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, key) {
+    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 {
+    parts = [];
+    bytes = 0;
+    nodes = 0;
+    ancestors = new Set();
+    budget;
+    constructor(budget) {
+        this.budget = budget;
+    }
+    text() {
+        return this.parts.join("");
+    }
+    add(text, bytes = text.length) {
+        this.bytes += bytes;
+        if (this.bytes > this.budget.bytes) {
+            throw new Limit("oversize");
+        }
+        this.parts.push(text);
+    }
+    string(value) {
+        // 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, depth) {
+        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;
+        }
+    }
+    object(value, depth) {
+        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);
+    }
+    array(value, depth) {
+        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("]");
+    }
+    record(value, depth) {
+        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, budget) {
+    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/dist/shared/compact-cards.js

@@ -0,0 +1,66 @@
+import { getMarkdownTheme, keyHint, truncateToVisualLines, } from "@earendil-works/pi-coding-agent";
+import { Box, Container, Markdown, Spacer, Text, truncateToWidth, } from "@earendil-works/pi-tui";
+import { actionText } from "./tui-action.js";
+function preview(content, expanded, theme, showHint = true) {
+    if (expanded) {
+        return content;
+    }
+    let cache;
+    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 = (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, types) {
+    let ui;
+    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 {
+                render(width) {
+                    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/dist/shared/journal-frames.js

@@ -1,5 +1,5 @@
 import * as fs from "node:fs";
-import { JsonProjection, } from "./json-projection.js";
+import { JsonProjection } from "./json-projection.js";
 import { errorDescription, isRecord } from "./unknown.js";
 /** Byte-framed JSONL. Publication framing is independent of malformed-record tolerance. */
 export class JournalFrames {
@@ -26,7 +26,7 @@ export class JournalFrames {
         this.projection = this.newProjection();
     }
     newProjection() {
-        return new JsonProjection(this.select, this.options.stringChunk, this.options.keys, this.options.limits);
+        return new JsonProjection(this.select, this.options.stringChunk);
     }
     part(bytes) {
         if (!this.nonblank && bytes.some((byte) => ![9, 10, 13, 32].includes(byte))) {
@@ -76,10 +76,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);
         }
     }