@fitchmultz/pi-subagents 0.47.0 → 0.49.0

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

package/dist/pi-intercom/transcript.js

@@ -0,0 +1,175 @@
+import { isRecord, isUnknownArray } from "../shared/unknown.js";
+import { Fault, label, object } from "./bridge-protocol.js";
+const SCAN_LIMIT = 1024;
+export function transcriptOptions(value = {}) {
+    const input = object(value, ["limit", "maxBytes", "cursor"]);
+    const limit = integer(input.limit, 50, 1, 100);
+    const maxBytes = integer(input.maxBytes, 65536, 256, 131072);
+    const cursor = input.cursor === undefined ? undefined : label(input.cursor, "cursor", 512);
+    return { limit, maxBytes, cursor };
+}
+function integer(value, fallback, min, max) {
+    const result = value === undefined ? fallback : value;
+    if (typeof result !== "number" || !Number.isInteger(result) || result < min || result > max) {
+        throw new Fault(400, "invalid_input", `Transcript limit must be an integer from ${min} to ${max}.`);
+    }
+    return result;
+}
+function textualContent(content) {
+    if (typeof content === "string") {
+        return { text: content, truncated: false };
+    }
+    if (!isUnknownArray(content)) {
+        return { text: "", truncated: false };
+    }
+    const pieces = [];
+    let remaining = 131073;
+    let truncated = content.length > 4096;
+    for (const part of content.slice(0, 4096)) {
+        if (remaining <= 0) {
+            truncated = true;
+            break;
+        }
+        if (isRecord(part) && part.type === "text" && typeof part.text === "string") {
+            const text = part.text.slice(0, remaining);
+            pieces.push(text);
+            truncated ||= text.length < part.text.length;
+            remaining -= text.length + 1;
+        }
+    }
+    return { text: pieces.join("\n"), truncated };
+}
+function visible(entry) {
+    if (entry.type === "custom_message") {
+        return entry.display ? { role: "custom", ...textualContent(entry.content) } : undefined;
+    }
+    if (entry.type !== "message") {
+        return undefined;
+    }
+    const message = entry.message;
+    if (message.role === "bashExecution") {
+        return {
+            role: "toolResult",
+            text: message.output,
+            truncated: nativeTruncation(message.truncated),
+        };
+    }
+    if (!["user", "assistant", "toolResult", "custom"].includes(message.role)) {
+        return undefined;
+    }
+    if (message.role === "custom" && !message.display) {
+        return undefined;
+    }
+    return "content" in message
+        ? { role: message.role, ...textualContent(message.content) }
+        : undefined;
+}
+function nativeTruncation(value) {
+    // Older saved bash entries may predate the native boolean field.
+    return value === true;
+}
+function boundedText(text, budget) {
+    // Slice before UTF-8 encoding to avoid copying arbitrarily large live tool output.
+    const bytes = Buffer.from(text.slice(0, budget));
+    if (bytes.length <= budget) {
+        return bytes.toString();
+    }
+    let end = budget;
+    while (end > 0 && (bytes[end] & 0xc0) === 0x80) {
+        end -= 1;
+    }
+    return bytes.subarray(0, end).toString();
+}
+function startId(manager, leaf, cursor) {
+    if (cursor === undefined) {
+        return { id: leaf, scanned: 0 };
+    }
+    let raw;
+    try {
+        raw = JSON.parse(Buffer.from(cursor, "base64url").toString("utf8"));
+    }
+    catch {
+        throw new Fault(400, "invalid_cursor", "Invalid transcript cursor.");
+    }
+    const data = object(raw, ["leaf", "before"]);
+    if (data.leaf !== leaf) {
+        throw new Fault(409, "branch_changed", "Active branch changed; request a new transcript page.");
+    }
+    const before = label(data.before, "cursor entry", 128);
+    let id = leaf;
+    for (let scanned = 0; id !== null && scanned < SCAN_LIMIT; scanned += 1) {
+        if (id === before) {
+            return { id, scanned };
+        }
+        id = manager.getEntry(id)?.parentId ?? null;
+    }
+    throw new Fault(400, "invalid_cursor", "Cursor is outside the bounded active branch.");
+}
+/** Finalized textual output on the selected branch; never builds full history/context. */
+export function readLiveTranscript(manager, input = {}) {
+    const options = transcriptOptions(input);
+    const leaf = manager.getLeafId();
+    const start = startId(manager, leaf, options.cursor);
+    let id = start.id;
+    let scanned = start.scanned;
+    const records = [];
+    let bytes = 0;
+    let textTruncated = false;
+    while (id !== null && scanned < SCAN_LIMIT) {
+        scanned += 1;
+        const entry = manager.getEntry(id);
+        if (!entry) {
+            textTruncated = true;
+            id = null;
+            break;
+        }
+        const record = transcriptRecord(entry, options.maxBytes - bytes);
+        if (record !== undefined) {
+            records.push(record);
+            bytes += Buffer.byteLength(record.text);
+            textTruncated ||= record.truncated;
+        }
+        id = entry.parentId;
+        if (records.length >= options.limit || bytes >= options.maxBytes) {
+            break;
+        }
+    }
+    return transcriptPage(manager, {
+        leaf,
+        records,
+        bytes,
+        textTruncated,
+        id,
+        scanLimitReached: scanned >= SCAN_LIMIT && id !== null,
+    });
+}
+function transcriptRecord(entry, budget) {
+    const output = visible(entry);
+    if (output === undefined || output.text.length === 0) {
+        return undefined;
+    }
+    const text = boundedText(output.text, budget);
+    return {
+        id: entry.id,
+        timestamp: entry.timestamp,
+        role: output.role,
+        text,
+        truncated: text !== output.text || output.truncated,
+    };
+}
+function transcriptPage(manager, state) {
+    const { leaf, records, bytes, textTruncated, id, scanLimitReached } = state;
+    return {
+        sessionId: manager.getSessionId(),
+        leafId: leaf,
+        records: records.reverse(),
+        bytes,
+        truncated: id !== null || textTruncated,
+        scanLimitReached,
+        ...(id !== null && !scanLimitReached
+            ? { cursor: Buffer.from(JSON.stringify({ leaf, before: id })).toString("base64url") }
+            : {}),
+        finalizedOnly: true,
+        streaming: "unavailable",
+    };
+}