@fitchmultz/pi-subagents 0.49.1 → 0.51.0

package/dist/pi-intercom/tools.js

@@ -1,24 +1,71 @@
-import { validateIntercomArguments, toolError, toolText } from "./tool-arguments.js";
+import { resolveConnectedTarget } from "./connection.js";
+import { validateIntercomArguments, toolError } from "./tool-arguments.js";
 import { errorMessage } from "./validation.js";
+function lastPage(result) {
+    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 },
+    };
+}
 export class IntercomTools {
     owners;
     constructor(owners) {
         this.owners = owners;
     }
-    async dispatch(active, params, signal, ctx) {
-        const scope = params.scope ?? "project";
+    async execute(params, signal, ctx) {
+        const invalid = validateIntercomArguments(params);
+        if (invalid) {
+            return invalid;
+        }
+        let active;
+        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":
@@ -27,25 +74,4 @@ export class IntercomTools {
                 return await this.owners.outbound.reply(active, params);
         }
     }
-    async execute(params, signal, ctx) {
-        let active;
-        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/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" &&
@@ -135,15 +166,25 @@ function validSessionTopics(session) {
         (session.topics === undefined ||
             (isUnknownArray(session.topics) && session.topics.every(isTopicUpdate))));
 }
+function validSessionLineage(value) {
+    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) {
+    return value === undefined || (typeof value === "string" && /^[a-f0-9]{64}$/.test(value));
+}
 export function isSessionRegistration(value) {
     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));
 }
@@ -198,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/ui/session-format.js

@@ -6,7 +6,7 @@ function shellQuote(value) {
     return `'${value.replace(/'/g, `'\\''`)}'`;
 }
 function localForkStartCommand() {
-    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) {
     const names = sessions
@@ -101,7 +101,7 @@ function noPeers(hidden) {
     }
     return `No other sessions connected. Start another intercom-enabled session with \`pi --name worker\`, then run \`intercom({ action: "list" })\` again. If you are dogfooding this local fork without installing it, start the peer with \`${localForkStartCommand()}\`.`;
 }
-export function formatSessionListSections(allSessions, id, scope = "project") {
+export function formatSessionListSections(allSessions, id, scope = "all") {
     const current = allSessions.find((session) => session.id === id);
     if (!current) {
         throw new Error("Current session is missing from intercom session list.");
@@ -118,7 +118,7 @@ export function formatSessionListSections(allSessions, id, scope = "project") {
     const currentSection = `**Current session:**\n${row(current, { ...options, self: true })}`;
     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/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" };
+    }
+}