@fitchmultz/pi-subagents 0.47.0 → 0.48.0

package/dist/pi-intercom/connection.js

@@ -1,8 +1,7 @@
-import { createHash } from "node:crypto";
 import { IntercomClient } from "./broker/client.js";
 import { spawnBrokerIfNeeded } from "./broker/spawn.js";
 import { asError, errorMessage } from "./validation.js";
-import { formatTargetOptions, resolveSessionTarget } from "./session-targets.js";
+import { formatTargetOptions, resolveSessionTarget, nativePeerId } from "./session-targets.js";
 /** Owns socket registration, coalesced connects and the reconnect/startup timers. */
 export class IntercomConnection {
     client = null;
@@ -195,7 +194,7 @@ export class IntercomConnection {
             if (reason !== "peer-awareness") {
                 await spawnBrokerIfNeeded(this.config.brokerCommand, this.config.brokerArgs);
             }
-            await next.connect(await this.lifecycle.registration(this.hooks.pendingAsks()), `pi-${createHash("sha256").update(sessionId).digest("hex").slice(0, 32)}`);
+            await next.connect(await this.lifecycle.registration(this.hooks.pendingAsks()), nativePeerId(sessionId));
             if (!this.lifecycle.live(ctx, generation)) {
                 await next.disconnect();
                 throw new Error("Intercom runtime no longer active");

package/dist/pi-intercom/inbound.js

@@ -1,7 +1,7 @@
-import { createHash } from "node:crypto";
 import { requestedDelivery, isBlockingSupervisorMessage } from "./inbound-record.js";
 import { formatAttachments } from "./message-format.js";
 import { readQuestionOwner } from "../runs/shared/supervisor-questions.js";
+import { nativePeerId } from "./session-targets.js";
 /** Validates origin and chooses admission; state/resources remain in their owners. */
 export class IntercomInbound {
     lifecycle;
@@ -19,9 +19,7 @@ export class IntercomInbound {
             return false;
         }
         const owner = readQuestionOwner(origin.runId);
-        return (owner?.sessionId === origin.ownerSessionId &&
-            from.id ===
-                `pi-${createHash("sha256").update(origin.ownerSessionId).digest("hex").slice(0, 32)}`);
+        return (owner?.sessionId === origin.ownerSessionId && from.id === nativePeerId(origin.ownerSessionId));
     }
     normalize(from, input) {
         const message = input.topic

package/dist/pi-intercom/index.js

@@ -8,6 +8,7 @@ import { InboundDeliveryOwner } from "./inbound-delivery.js";
 import { ReplyWait } from "./reply-wait.js";
 import { IntercomConnection } from "./connection.js";
 import { IntercomInbound } from "./inbound.js";
+import { NativeControls } from "./native-control.js";
 import { IntercomOutbound } from "./outbound.js";
 import { IntercomInspection } from "./inspection.js";
 import { IntercomTopicActions } from "./topic-actions.js";
@@ -31,7 +32,11 @@ export default function piIntercomExtension(pi) {
     const connection = new IntercomConnection(lifecycle, config, topics, {
         restoring: () => delivery.restoring,
         pendingAsks: () => replies.listPending().length,
-        incoming: (ctx, from, message) => inbound.receive(ctx, from, message),
+        incoming: async (ctx, from, message) => {
+            if (!(await controls.receive(ctx, from, message))) {
+                await inbound.receive(ctx, from, message);
+            }
+        },
         peerLeft: (id) => {
             wait.peerDisconnected(id);
             journal.peerLeft(id);
@@ -42,6 +47,7 @@ export default function piIntercomExtension(pi) {
             }
         },
     });
+    const controls = new NativeControls(lifecycle, connection);
     const delivery = new InboundDeliveryOwner(pi, lifecycle, journal, {
         replies,
         syncStatus: () => connection.syncStatus(),

package/dist/pi-intercom/native-control-auth.js

@@ -0,0 +1,80 @@
+import { X509Certificate } from "node:crypto";
+import { join } from "node:path";
+import { homedir } from "node:os";
+import { existsSync } from "node:fs";
+import { loadControlPolicy } from "./bridge-config.js";
+import { getPiAgentDir } from "./agent-dir.js";
+import { fingerprint } from "./bridge-protocol.js";
+export function authenticatedCertificateChain(socket) {
+    const blocks = [];
+    const seen = new Set();
+    let cert = socket.getPeerCertificate(true);
+    for (let depth = 0; depth < 8; depth += 1) {
+        const parsed = new X509Certificate(cert.raw);
+        if (seen.has(parsed.fingerprint256)) {
+            break;
+        }
+        seen.add(parsed.fingerprint256);
+        blocks.push(parsed.toString());
+        cert = cert.issuerCertificate;
+    }
+    return blocks.join("\n");
+}
+function certificates(pem) {
+    const blocks = pem.match(/-----BEGIN CERTIFICATE-----[\s\S]*?-----END CERTIFICATE-----/g);
+    if (!blocks || blocks.length > 8) {
+        throw new Error("Invalid bounded certificate chain.");
+    }
+    return blocks.map((block) => new X509Certificate(block));
+}
+function validNow(cert) {
+    return Date.parse(cert.validFrom) <= Date.now() && Date.parse(cert.validTo) > Date.now();
+}
+function trustedChain(chain, roots) {
+    let current = chain.at(0);
+    if (current === undefined || current.ca || !validNow(current)) {
+        return false;
+    }
+    for (let depth = 0; depth < 8; depth += 1) {
+        const subject = current;
+        const issuer = [...roots, ...chain.slice(1)].find((candidate) => candidate.ca &&
+            validNow(candidate) &&
+            subject.checkIssued(candidate) &&
+            subject.verify(candidate.publicKey));
+        if (!issuer) {
+            return false;
+        }
+        if (roots.some((root) => root.fingerprint256 === issuer.fingerprint256)) {
+            return true;
+        }
+        current = issuer;
+    }
+    return false;
+}
+function controlPolicyPath() {
+    const configured = process.env.PI_INTERCOM_BRIDGE_CONFIG;
+    if (configured !== undefined) {
+        return configured;
+    }
+    const standard = join(getPiAgentDir(), "intercom", "bridge.json");
+    return existsSync(standard) ? standard : join(homedir(), ".pi", "intercom-bridge", "config.json");
+}
+/** Unix broker peers are same-user trusted. Names/payload claims grant no authority. */
+export function authorizedControlPeer(peerId, certificate) {
+    try {
+        const configPath = controlPolicyPath();
+        const config = loadControlPolicy(configPath);
+        const chain = certificates(certificate);
+        const client = chain.at(0);
+        if (client === undefined) {
+            return false;
+        }
+        const fp = fingerprint(client.fingerprint256);
+        return (peerId === `remote-${fp.toLowerCase()}` &&
+            config.clients.has(fp) &&
+            trustedChain(chain, certificates(config.ca.toString("utf8"))));
+    }
+    catch {
+        return false;
+    }
+}

package/dist/pi-intercom/native-control-protocol.js

@@ -0,0 +1,111 @@
+import { isRecord, isUnknownArray } from "../shared/unknown.js";
+export const CONTROL_SCHEMA = "pi-intercom/control-v1";
+export const CONTROL_FALLBACK = "Native Intercom metadata exchange (no conversation response needed).";
+export function isControlVerb(value) {
+    return (value === "capabilities" || value === "cancel" || value === "stop" || value === "transcript");
+}
+export function isControlRequest(value) {
+    return (isRecord(value) &&
+        value.schema === CONTROL_SCHEMA &&
+        value.kind === "request" &&
+        isControlVerb(value.verb) &&
+        typeof value.certificate === "string" &&
+        value.certificate.length <= 16384 &&
+        Object.keys(value).every((key) => ["schema", "kind", "verb", "certificate", "options"].includes(key)));
+}
+export function isControlResult(value) {
+    if (!isRecord(value) ||
+        value.schema !== CONTROL_SCHEMA ||
+        value.kind !== "result" ||
+        !isControlVerb(value.verb)) {
+        return false;
+    }
+    return (validResultFields(value) &&
+        validResultPayload(value) &&
+        Buffer.byteLength(JSON.stringify(value)) <= 1024 * 1024);
+}
+function optionalText(value, max) {
+    return value === undefined || (typeof value === "string" && value.length <= max);
+}
+function validResultFields(value) {
+    const fields = new Set([
+        "schema",
+        "kind",
+        "verb",
+        "status",
+        "mode",
+        "idle",
+        "pendingInput",
+        "queueCleared",
+        "processExited",
+        "stopSupport",
+        "reason",
+        "transcript",
+        "verbs",
+    ]);
+    return (Object.keys(value).every((key) => fields.has(key)) &&
+        typeof value.status === "string" &&
+        ["ok", "denied", "cancel_requested", "shutdown_requested", "unsupported", "failed"].includes(value.status) &&
+        optionalText(value.reason, 2048) &&
+        optionalText(value.mode, 64) &&
+        [value.idle, value.pendingInput].every((flag) => flag === undefined || typeof flag === "boolean") &&
+        [value.queueCleared, value.processExited].every((flag) => flag === undefined || flag === false));
+}
+function validResultPayload(value) {
+    if (value.stopSupport !== undefined &&
+        (typeof value.stopSupport !== "string" ||
+            !["native_shutdown", "requires_activity", "host_dependent"].includes(value.stopSupport))) {
+        return false;
+    }
+    if (value.verbs !== undefined &&
+        (!isUnknownArray(value.verbs) || !value.verbs.every(isControlVerb))) {
+        return false;
+    }
+    return value.transcript === undefined || validTranscript(value.transcript);
+}
+function validTranscript(value) {
+    if (!isRecord(value) || !isUnknownArray(value.records) || value.records.length > 100) {
+        return false;
+    }
+    const fields = new Set([
+        "sessionId",
+        "leafId",
+        "records",
+        "bytes",
+        "truncated",
+        "cursor",
+        "scanLimitReached",
+        "finalizedOnly",
+        "streaming",
+    ]);
+    return (Object.keys(value).every((key) => fields.has(key)) &&
+        typeof value.sessionId === "string" &&
+        value.sessionId.length <= 512 &&
+        (value.leafId === null || typeof value.leafId === "string") &&
+        value.records.every(validTranscriptRecord) &&
+        validTranscriptMetadata(value));
+}
+function validTranscriptMetadata(value) {
+    return (typeof value.bytes === "number" &&
+        Number.isInteger(value.bytes) &&
+        value.bytes >= 0 &&
+        value.bytes <= 131072 &&
+        typeof value.truncated === "boolean" &&
+        optionalText(value.cursor, 512) &&
+        typeof value.scanLimitReached === "boolean" &&
+        value.finalizedOnly === true &&
+        value.streaming === "unavailable");
+}
+function validTranscriptRecord(value) {
+    if (!isRecord(value)) {
+        return false;
+    }
+    const fields = new Set(["id", "timestamp", "role", "text", "truncated"]);
+    return (Object.keys(value).every((key) => fields.has(key)) &&
+        [value.id, value.timestamp].every((field) => typeof field === "string" && field.length <= 512) &&
+        typeof value.role === "string" &&
+        ["user", "assistant", "toolResult", "custom"].includes(value.role) &&
+        typeof value.text === "string" &&
+        Buffer.byteLength(value.text) <= 131072 &&
+        typeof value.truncated === "boolean");
+}

package/dist/pi-intercom/native-control.js

@@ -0,0 +1,130 @@
+import { authorizedControlPeer } from "./native-control-auth.js";
+import { CONTROL_FALLBACK, CONTROL_SCHEMA, isControlRequest, } from "./native-control-protocol.js";
+import { readLiveTranscript, transcriptOptions } from "./transcript.js";
+export class NativeControls {
+    lifecycle;
+    connection;
+    constructor(lifecycle, connection) {
+        this.lifecycle = lifecycle;
+        this.connection = connection;
+    }
+    result(ctx, request) {
+        const base = {
+            schema: CONTROL_SCHEMA,
+            kind: "result",
+            verb: request.verb,
+            mode: ctx.mode,
+            idle: ctx.isIdle(),
+            pendingInput: ctx.hasPendingMessages(),
+            queueCleared: false,
+            processExited: false,
+        };
+        if (request.verb !== "transcript" && request.options !== undefined) {
+            throw new Error("Only transcript accepts options.");
+        }
+        const stopSupport = stopCapability(ctx);
+        switch (request.verb) {
+            case "capabilities":
+                return {
+                    ...base,
+                    status: "ok",
+                    stopSupport,
+                    verbs: ["capabilities", "cancel", "stop", "transcript"],
+                };
+            case "transcript":
+                return {
+                    ...base,
+                    status: "ok",
+                    transcript: readLiveTranscript(ctx.sessionManager, transcriptOptions(request.options)),
+                };
+            case "cancel":
+                return {
+                    ...base,
+                    status: "cancel_requested",
+                    reason: "Native current-operation abort; accepted queued input is not cleared.",
+                };
+            case "stop":
+                return {
+                    ...base,
+                    status: ctx.mode === "print" || ctx.mode === "json" ? "unsupported" : "shutdown_requested",
+                    stopSupport,
+                    reason: "Native shutdown/current-operation abort requested, not process exit. Idle RPC is deferred until a native command/settlement; print/JSON/SDK have no guaranteed shutdown binding.",
+                };
+        }
+    }
+    async receive(ctx, from, message) {
+        if (!Object.hasOwn(message, "control")) {
+            return false;
+        }
+        // Even malformed/response envelopes never enter conversation journaling or inference.
+        const request = message.control;
+        if (!isControlRequest(request) ||
+            message.replyTo !== undefined ||
+            message.delivery !== "passive" ||
+            message.expectsReply === true) {
+            return true;
+        }
+        const generation = this.lifecycle.generation;
+        const active = this.connection.active;
+        if (!active || !this.lifecycle.live(ctx, generation)) {
+            return true;
+        }
+        const result = this.admit(ctx, from.id, request);
+        // Receipt is acknowledged before shutdown can retire this socket/context.
+        await active.send(from.id, {
+            text: CONTROL_FALLBACK,
+            delivery: "passive",
+            replyTo: message.id,
+            control: result,
+        });
+        this.apply(ctx, generation, { active, peer: from.id, request, result });
+        return true;
+    }
+    apply(ctx, generation, state) {
+        const { active, peer, request, result } = state;
+        if (!this.lifecycle.live(ctx, generation) ||
+            this.connection.active !== active ||
+            !authorizedControlPeer(peer, request.certificate)) {
+            return;
+        }
+        if (result.status === "shutdown_requested" ||
+            (result.status === "unsupported" && request.verb === "stop")) {
+            ctx.shutdown();
+            if (this.lifecycle.live(ctx, generation)) {
+                ctx.abort();
+            }
+        }
+        else if (result.status === "cancel_requested") {
+            ctx.abort();
+        }
+    }
+    admit(ctx, peer, request) {
+        if (!authorizedControlPeer(peer, request.certificate)) {
+            return {
+                schema: CONTROL_SCHEMA,
+                kind: "result",
+                verb: request.verb,
+                status: "denied",
+                reason: "Sender certificate is not currently authorized by private bridge configuration.",
+            };
+        }
+        try {
+            return this.result(ctx, request);
+        }
+        catch {
+            return {
+                schema: CONTROL_SCHEMA,
+                kind: "result",
+                verb: request.verb,
+                status: "failed",
+                reason: "Native control input/state is unavailable.",
+            };
+        }
+    }
+}
+function stopCapability(ctx) {
+    if (ctx.mode === "tui") {
+        return "native_shutdown";
+    }
+    return ctx.mode === "rpc" ? "requires_activity" : "host_dependent";
+}

package/dist/pi-intercom/saved-transcript.js

@@ -0,0 +1,135 @@
+import { constants, openSync, closeSync, fstatSync } from "node:fs";
+import { loadNativeSession } from "../shared/native-session-loader.js";
+import { scanJournal } from "../shared/journal-reader.js";
+import { Fault } from "./bridge-protocol.js";
+import { readLiveTranscript } from "./transcript.js";
+const FILE_BYTES = 64 * 1024 * 1024;
+const ENTRY_COUNT = 50000;
+const TEXT_LIMIT = 131072;
+const fields = new Set([
+    "type",
+    "id",
+    "parentId",
+    "timestamp",
+    "version",
+    "cwd",
+    "customType",
+    "display",
+    "content",
+]);
+/** Only branch structure and public textual content are hydrated, never image/provider/custom data. */
+const transcriptProjection = (path) => {
+    if (path.length === 0) {
+        return true;
+    }
+    if (path[0] === "message") {
+        return messageField(path.slice(1));
+    }
+    if (path[0] === "content") {
+        return contentField(path.slice(1));
+    }
+    return path.length === 1 && fields.has(String(path[0])) ? 4096 : false;
+};
+function messageField(path) {
+    if (path.length === 0) {
+        return true;
+    }
+    if (path[0] === "content") {
+        return contentField(path.slice(1));
+    }
+    return path.length === 1 && ["role", "output", "display", "truncated"].includes(String(path[0]))
+        ? TEXT_LIMIT
+        : false;
+}
+function contentField(path) {
+    return path.length < 2 || (path.length === 2 && ["type", "text"].includes(String(path[1])))
+        ? TEXT_LIMIT
+        : false;
+}
+function textField(path) {
+    if (path[0] === "message") {
+        return ((path.length === 2 && ["content", "output"].includes(String(path[1]))) ||
+            (path.length === 4 && path[1] === "content" && path[3] === "text"));
+    }
+    return path[0] === "content" && (path.length === 1 || (path.length === 3 && path[2] === "text"));
+}
+function savedLines(fd, size) {
+    const lines = [];
+    const cut = new Set();
+    const lengths = new Map();
+    scanJournal(fd, transcriptProjection, ({ value }) => {
+        if (lines.length >= ENTRY_COUNT) {
+            throw new Fault(413, "transcript_too_large", "Saved journal exceeds the 50000-entry budget.");
+        }
+        lines.push(JSON.stringify(value));
+        lengths.clear();
+    }, {
+        policy: "inspect",
+        requireNewline: true,
+        end: size,
+        limits: { depth: 64, nodes: 16384, arrayLength: 4096, keyLength: 512 },
+        malformed: (_start, _end, error) => {
+            if (error instanceof RangeError) {
+                throw new Fault(413, "transcript_too_large", "Saved record exceeds projection limits.");
+            }
+            lengths.clear();
+            cut.delete(lines.length);
+        },
+        stringChunk: (path, chunk) => {
+            if (textField(path)) {
+                const key = JSON.stringify(path);
+                const count = (lengths.get(key) ?? 0) + chunk.length;
+                lengths.set(key, count);
+                if (count > TEXT_LIMIT) {
+                    cut.add(lines.length);
+                }
+            }
+        },
+    });
+    return { lines, cut };
+}
+/** Internal hook: caller MUST resolve a catalog-approved saved ID/name, never accept an HTTP filepath. */
+export async function readSavedTranscript(packageRoot, approvedFile, options = {}) {
+    const sdk = await loadNativeSession(packageRoot);
+    const fd = openSync(approvedFile, constants.O_RDONLY | constants.O_NOFOLLOW);
+    try {
+        const before = fstatSync(fd);
+        if (!before.isFile() || before.size > FILE_BYTES) {
+            throw new Fault(413, "transcript_too_large", "Saved journal exceeds the 64 MiB read budget.");
+        }
+        const { lines, cut } = savedLines(fd, before.size);
+        const after = fstatSync(fd);
+        if (after.size !== before.size ||
+            after.mtimeMs !== before.mtimeMs ||
+            after.ctimeMs !== before.ctimeMs) {
+            throw new Fault(409, "session_changed", "Saved journal changed during reading; refresh the catalog.");
+        }
+        const entries = sdk.parseSessionEntries(lines.join("\n"));
+        return savedPage(entries, cut, options, sdk);
+    }
+    finally {
+        closeSync(fd);
+    }
+}
+function savedPage(entries, cut, options, sdk) {
+    const header = entries.find((entry) => entry.type === "session");
+    if (header === undefined) {
+        throw new Fault(409, "invalid_session", "Saved journal has no native session header.");
+    }
+    const legacy = (header.version ?? 1) < 2;
+    if (legacy && options.cursor !== undefined) {
+        throw new Fault(409, "cursor_unavailable", "Legacy journals have no stable entry IDs; request a fresh bounded recent transcript.");
+    }
+    // Native inMemory reconstructs branch state/migrations without ever opening or writing the file.
+    const manager = sdk.SessionManager.inMemory(header.cwd, undefined, entries);
+    const page = readLiveTranscript(manager, options);
+    const cutIds = new Set(entries.flatMap((entry, index) => entry.type !== "session" && cut.has(index) ? [entry.id] : []));
+    const records = page.records.map((entry) => cutIds.has(entry.id) ? { ...entry, truncated: true } : entry);
+    return {
+        ...page,
+        // ponytail: v1 has no persisted entry IDs; use catalog snapshot cursors if legacy pagination is needed.
+        cursor: legacy ? undefined : page.cursor,
+        records,
+        truncated: page.truncated || records.some((entry) => entry.truncated),
+    };
+}

package/dist/pi-intercom/session-targets.js

@@ -2,6 +2,9 @@ import { execFile } from "node:child_process";
 import { createHash } from "node:crypto";
 import path from "node:path";
 export const MIN_SESSION_TARGET_PREFIX_LENGTH = 8;
+export function nativePeerId(sessionId) {
+    return `pi-${createHash("sha256").update(sessionId).digest("hex").slice(0, 32)}`;
+}
 export function shortSessionId(sessionId) {
     return sessionId.slice(0, MIN_SESSION_TARGET_PREFIX_LENGTH);
 }