@fitchmultz/pi-subagents 0.46.2 → 0.48.0

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

@@ -0,0 +1,104 @@
+import { randomUUID } from "node:crypto";
+import { Fault, wait } from "./bridge-protocol.js";
+import { CONTROL_FALLBACK, CONTROL_SCHEMA, isControlResult, } from "./native-control-protocol.js";
+/** One bounded request owner; exact socket-derived peer, replyTo, version and verb correlation. */
+export class ControlReplies {
+    pending = new Map();
+    open(peer, verb, timeoutMs) {
+        if (this.pending.size >= 8) {
+            throw new Fault(429, "too_many_controls", "At most eight native controls may be in flight.");
+        }
+        const id = randomUUID();
+        const { promise: reply, resolve, reject } = Promise.withResolvers();
+        // A disconnect may reject while send is awaiting its broker receipt.
+        void reply.catch(() => {
+            /* Request owner observes rejection after its send receipt. */
+        });
+        const timer = setTimeout(() => reject(new Fault(504, "control_unconfirmed", "No correlated native response. Owner may be old/unavailable; execution is unknown. Do not automatically retry.", { id, deliveryUnknown: true })), timeoutMs);
+        const pending = { peer, verb, reply, resolve, reject, timer, disconnected: false };
+        this.pending.set(id, pending);
+        return {
+            id,
+            reply,
+            clear: () => this.clear(id),
+            get observedDisconnected() {
+                return pending.disconnected;
+            },
+        };
+    }
+    async request(client, operation, context) {
+        context.onPeer(operation.peer);
+        const waiting = this.open(operation.peer, operation.verb, operation.timeoutMs);
+        try {
+            context.guard();
+            const receipt = await wait(client.send(operation.peer, {
+                text: CONTROL_FALLBACK,
+                messageId: waiting.id,
+                delivery: "passive",
+                control: {
+                    schema: CONTROL_SCHEMA,
+                    kind: "request",
+                    verb: operation.verb,
+                    certificate: operation.certificate,
+                    options: operation.options,
+                },
+            }), context.signal).catch((error) => {
+                context.guard();
+                if (error instanceof Fault) {
+                    throw error;
+                }
+                throw new Fault(504, "control_unconfirmed", "Broker receipt was not received; native execution is unknown. Do not automatically retry.", { id: waiting.id, deliveryUnknown: true });
+            });
+            context.guard();
+            if (!receipt.accepted) {
+                throw new Fault(409, "delivery_failed", receipt.reason ?? "Broker rejected native control.", { id: receipt.id });
+            }
+            const result = await wait(waiting.reply, context.signal);
+            context.guard();
+            return {
+                ...receipt,
+                peer: operation.peer,
+                status: result.status,
+                native: result,
+                observedDisconnected: waiting.observedDisconnected,
+                processExited: false,
+            };
+        }
+        finally {
+            waiting.clear();
+        }
+    }
+    receive(peer, message) {
+        if (!Object.hasOwn(message, "control")) {
+            return false;
+        }
+        const pending = message.replyTo === undefined ? undefined : this.pending.get(message.replyTo);
+        if (pending &&
+            pending.peer === peer &&
+            message.delivery === "passive" &&
+            isControlResult(message.control) &&
+            message.control.verb === pending.verb) {
+            pending.resolve(message.control);
+        }
+        // Unsolicited/spoofed/malformed control results do not enter the remote mailbox.
+        return true;
+    }
+    peerLeft(peer) {
+        for (const [id, pending] of this.pending) {
+            if (pending.peer === peer) {
+                pending.disconnected = true;
+                pending.reject(new Fault(409, "peer_disconnected", "Native peer disconnected; this does not establish process exit.", { id, observedDisconnected: true, processExited: false, deliveryUnknown: true }));
+            }
+        }
+    }
+    close(error) {
+        for (const [id, pending] of this.pending) {
+            pending.reject(error);
+            this.clear(id);
+        }
+    }
+    clear(id) {
+        clearTimeout(this.pending.get(id)?.timer);
+        this.pending.delete(id);
+    }
+}

package/dist/pi-intercom/bridge-files.js

@@ -0,0 +1,47 @@
+import { constants, closeSync, fstatSync, fsyncSync, openSync, readFileSync, renameSync, rmSync, writeFileSync, } from "node:fs";
+import { dirname } from "node:path";
+import { randomUUID } from "node:crypto";
+export function readBridgeFile(path, privateFile, limit) {
+    const fd = openSync(path, constants.O_RDONLY | constants.O_NOFOLLOW);
+    try {
+        const stat = fstatSync(fd);
+        if (!stat.isFile() || stat.size > limit) {
+            throw new Error("Configuration/TLS file must be a bounded regular file.");
+        }
+        if (privateFile && (stat.uid !== process.getuid?.() || (stat.mode & 0o777) !== 0o600)) {
+            throw new Error("Config and TLS key must be owned by the current user with mode 0600.");
+        }
+        const data = readFileSync(fd);
+        if (data.length > limit) {
+            throw new Error("Configuration/TLS file exceeds its size limit.");
+        }
+        return data;
+    }
+    finally {
+        closeSync(fd);
+    }
+}
+export function writeBridgeJson(path, value) {
+    const temporary = `${path}.${randomUUID()}.tmp`;
+    const fd = openSync(temporary, constants.O_WRONLY | constants.O_CREAT | constants.O_EXCL | constants.O_NOFOLLOW, 0o600);
+    try {
+        try {
+            writeFileSync(fd, JSON.stringify(value));
+            fsyncSync(fd);
+        }
+        finally {
+            closeSync(fd);
+        }
+        renameSync(temporary, path);
+        const directory = openSync(dirname(path), constants.O_RDONLY | constants.O_DIRECTORY);
+        try {
+            fsyncSync(directory);
+        }
+        finally {
+            closeSync(directory);
+        }
+    }
+    finally {
+        rmSync(temporary, { force: true });
+    }
+}

package/dist/pi-intercom/bridge-groups.js

@@ -0,0 +1,135 @@
+import { lstatSync, mkdirSync } from "node:fs";
+import { join, matchesGlob } from "node:path";
+import { readBridgeFile, writeBridgeJson } from "./bridge-files.js";
+import { isUnknownArray, hasErrorCode } from "../shared/unknown.js";
+import { Fault, label, object } from "./bridge-protocol.js";
+import { resolveSessionTarget, nativePeerId } from "./session-targets.js";
+const GROUP_LIMIT = 64;
+function normalizedGroup(value) {
+    const input = object(value, ["name", "members", "namePattern", "cwdPattern", "match"]);
+    if (input.match === undefined) {
+        return input;
+    }
+    if ([input.members, input.namePattern, input.cwdPattern].some((field) => field !== undefined)) {
+        throw new Fault(400, "invalid_input", "Use match or canonical selectors, not both.");
+    }
+    const match = typeof input.match === "string"
+        ? { nameglob: input.match }
+        : object(input.match, ["id", "nameglob", "cwd"]);
+    return {
+        name: input.name,
+        members: typeof match.id === "string" ? [match.id] : match.id,
+        namePattern: match.nameglob,
+        cwdPattern: match.cwd,
+    };
+}
+export function groupDefinition(value) {
+    const input = normalizedGroup(value);
+    const name = label(input.name, "group name", 64).trim();
+    if (input.members !== undefined &&
+        (!isUnknownArray(input.members) || input.members.length > 256)) {
+        throw new Fault(400, "invalid_input", "members must contain at most 256 peer IDs/names.");
+    }
+    const members = isUnknownArray(input.members)
+        ? [...new Set(input.members.map((member) => label(member, "member", 512).trim()))]
+        : undefined;
+    const namePattern = input.namePattern === undefined ? undefined : label(input.namePattern, "name pattern", 128);
+    const cwdPattern = input.cwdPattern === undefined ? undefined : label(input.cwdPattern, "cwd pattern", 512);
+    if (members === undefined && namePattern === undefined && cwdPattern === undefined) {
+        throw new Fault(400, "invalid_input", "Define explicit members or at least one glob pattern.");
+    }
+    return { name, members, namePattern, cwdPattern };
+}
+function privateDirectory(path) {
+    mkdirSync(path, { recursive: true, mode: 0o700 });
+    const stat = lstatSync(path);
+    if (!stat.isDirectory() ||
+        stat.isSymbolicLink() ||
+        stat.uid !== process.getuid?.() ||
+        (stat.mode & 0o777) !== 0o700) {
+        throw new Fault(503, "state_unavailable", "Group stateDir must be owned by the current user with mode 0700.");
+    }
+}
+export function nativePeers(peers, source) {
+    return peers.filter((peer) => /^pi-[a-f0-9]{32}$/.test(peer.id) && peer.id !== source);
+}
+export class Groups {
+    stateDir;
+    constructor(stateDir) {
+        this.stateDir = stateDir;
+        privateDirectory(stateDir);
+    }
+    file(fingerprint) {
+        if (!/^[a-fA-F0-9]{64}$/.test(fingerprint)) {
+            throw new Fault(403, "unauthorized", "Invalid identity.");
+        }
+        return join(this.stateDir, `groups-${fingerprint.toLowerCase()}.json`);
+    }
+    list(fingerprint) {
+        let raw;
+        try {
+            raw = JSON.parse(readBridgeFile(this.file(fingerprint), true, 1024 * 1024).toString("utf8"));
+        }
+        catch (error) {
+            if (hasErrorCode(error, "ENOENT")) {
+                return [];
+            }
+            throw error;
+        }
+        if (!isUnknownArray(raw) || raw.length > GROUP_LIMIT) {
+            throw new Fault(503, "state_unavailable", "Invalid group state.");
+        }
+        return raw.map(groupDefinition);
+    }
+    upsert(fingerprint, group) {
+        privateDirectory(this.stateDir);
+        const groups = this.list(fingerprint).filter((entry) => entry.name !== group.name);
+        if (groups.length >= GROUP_LIMIT) {
+            throw new Fault(409, "group_limit", "At most 64 groups are allowed per identity.");
+        }
+        groups.push(groupDefinition(group));
+        const file = this.file(fingerprint);
+        const serialized = JSON.stringify(groups);
+        if (Buffer.byteLength(serialized) > 1024 * 1024) {
+            throw new Fault(413, "state_too_large", "Group definitions exceed the 1 MiB identity budget.");
+        }
+        writeBridgeJson(file, groups);
+        return groups;
+    }
+    targets(fingerprint, name, peers) {
+        if (name === undefined) {
+            return { peers: nativePeers(peers), errors: [] };
+        }
+        const group = this.list(fingerprint).find((entry) => entry.name === name);
+        if (!group) {
+            throw new Fault(404, "unknown_group", "Define this group before sending to it.");
+        }
+        return selectTargets(group, nativePeers(peers));
+    }
+}
+function selectTargets(group, peers) {
+    const selected = new Map();
+    const errors = [];
+    for (const member of group.members ?? []) {
+        const result = resolveSessionTarget(peers, member);
+        const target = result.target ?? peers.find((peer) => peer.id === nativePeerId(member));
+        if (target) {
+            selected.set(target.id, target);
+        }
+        else {
+            errors.push({ member, code: result.status === "none" ? "peer_offline" : "ambiguous_target" });
+        }
+    }
+    if (group.namePattern !== undefined || group.cwdPattern !== undefined) {
+        for (const peer of peers) {
+            if (matchesSelectors(group, peer)) {
+                selected.set(peer.id, peer);
+            }
+        }
+    }
+    return { peers: [...selected.values()], errors };
+}
+function matchesSelectors(group, peer) {
+    return ((group.namePattern === undefined || matchesGlob(peer.name ?? "", group.namePattern)) &&
+        (group.cwdPattern === undefined || matchesGlob(peer.cwd, group.cwdPattern)));
+}

package/dist/pi-intercom/bridge-http.js

@@ -1,4 +1,4 @@
-import { BODY_LIMIT, Fault } from "./bridge-protocol.js";
+import { BODY_LIMIT, Fault, BroadcastFault } from "./bridge-protocol.js";
 import { errorMessage } from "../shared/unknown.js";
 function validateHeaders(req) {
     const type = req.headers["content-type"];
@@ -84,3 +84,10 @@ export function reply(res, requestId, status, data) {
     });
     res.end(payload);
 }
+export function replyFault(res, requestId, fault) {
+    reply(res, requestId, fault.status, {
+        ok: false,
+        ...(fault instanceof BroadcastFault ? fault.outcome : {}),
+        error: { code: fault.code, message: fault.message, ...fault.details },
+    });
+}

package/dist/pi-intercom/bridge-launch-journal.js

@@ -0,0 +1,84 @@
+import { statSync } from "node:fs";
+import { loadNativeSession } from "../shared/native-session-loader.js";
+import { isRecord } from "../shared/unknown.js";
+import { Fault, cancelled, wait } from "./bridge-protocol.js";
+import { trustedJournal, inspectResumeIdentity } from "./bridge-catalog.js";
+import { nativePeerId } from "./session-targets.js";
+export function validateLaunchState(saved, state) {
+    if (state.sessionId !== saved.sessionId ||
+        state.sessionFile !== saved.sessionFile ||
+        state.sessionName !== saved.name ||
+        state.isStreaming !== false ||
+        state.pendingMessageCount !== 0 ||
+        !isRecord(state.model)) {
+        throw new Fault(503, "readiness_failed", "Pi did not start idle with the exact saved session.");
+    }
+    if (saved.model &&
+        (state.model.provider !== saved.model.provider || state.model.id !== saved.model.modelId)) {
+        throw new Fault(503, "model_restore_failed", "Pi could not restore the saved model exactly; no task submitted and no silent fallback allowed.");
+    }
+}
+function journal(manager) {
+    const sessionFile = manager.getSessionFile();
+    if (sessionFile === undefined) {
+        throw new Fault(503, "journal_invalid", "Native journal was not persisted.");
+    }
+    const branch = manager.getBranch();
+    const change = branch.findLast((entry) => entry.type === "model_change");
+    const model = change?.type === "model_change"
+        ? { provider: change.provider, modelId: change.modelId }
+        : (manager.buildSessionContext().model ?? undefined);
+    return {
+        sessionId: manager.getSessionId(),
+        peerId: nativePeerId(manager.getSessionId()),
+        sessionFile,
+        name: manager.getSessionName(),
+        cwd: manager.getCwd(),
+        model,
+    };
+}
+export async function createLaunchJournal(policy, target, signal) {
+    const { SessionManager: Manager } = await wait(loadNativeSession(policy.packageRoot), signal);
+    cancelled(signal);
+    const storage = statSync(policy.sessionDir);
+    if (!storage.isDirectory() ||
+        storage.uid !== process.getuid?.() ||
+        (storage.mode & 0o777) !== 0o700) {
+        throw new Fault(503, "storage_invalid", "Private launch storage is no longer valid.");
+    }
+    const previous = process.umask(0o077);
+    try {
+        const manager = Manager.create(target.cwd, policy.sessionDir);
+        manager.appendSessionInfo(target.name);
+        if (policy.provider !== undefined && policy.model !== undefined) {
+            manager.appendModelChange(policy.provider, policy.model);
+        }
+        manager.appendMessage({ role: "user", content: policy.context, timestamp: Date.now() });
+        const result = journal(manager);
+        trustedJournal(policy, result.sessionFile);
+        if ((statSync(result.sessionFile).mode & 0o777) !== 0o600) {
+            throw new Fault(503, "journal_invalid", "New native journal was not privately persisted.");
+        }
+        return result;
+    }
+    finally {
+        process.umask(previous);
+    }
+}
+export async function resumeLaunchJournal(policy, saved, signal) {
+    const sdk = await wait(loadNativeSession(policy.packageRoot), signal);
+    cancelled(signal);
+    trustedJournal(policy, saved.sessionFile);
+    validateResumeIdentity(saved, await inspectResumeIdentity(saved.sessionFile, sdk, signal));
+    cancelled(signal);
+    const result = journal(sdk.SessionManager.open(saved.sessionFile));
+    validateResumeIdentity(saved, result);
+    return result;
+}
+function validateResumeIdentity(saved, actual) {
+    if (actual.sessionId !== saved.sessionId ||
+        actual.cwd !== saved.cwd ||
+        actual.name !== saved.name) {
+        throw new Fault(409, "journal_changed", "Native session identity changed while preparing resume.");
+    }
+}

package/dist/pi-intercom/bridge-launch-policy.js

@@ -1,7 +1,7 @@
 import { lstatSync, readFileSync, realpathSync, statSync } from "node:fs";
 import { isAbsolute, join, relative } from "node:path";
 import { isRecord, isUnknownArray } from "../shared/unknown.js";
-import { label, object, text } from "./bridge-protocol.js";
+import { Fault, label, object, text } from "./bridge-protocol.js";
 function absolute(value, field) {
     const path = label(value, field, 4096);
     if (!isAbsolute(path)) {
@@ -34,8 +34,8 @@ function executable(packageRoot) {
     }
     const bin = label(manifest.bin.pi, "Pi manifest bin", 4096);
     const cli = realpathSync(join(packageRoot, bin));
-    const within = relative(packageRoot, cli);
-    if (within.startsWith("..") || isAbsolute(within) || !statSync(cli).isFile()) {
+    const suffix = relative(packageRoot, cli);
+    if (suffix.startsWith("..") || isAbsolute(suffix) || !statSync(cli).isFile()) {
         throw new Error("Pi bin must be a file inside the pinned package.");
     }
     return cli;
@@ -46,6 +46,65 @@ function extensions(value) {
     }
     return value.map((entry) => absolute(entry, "extension path"));
 }
+function directories(value, owned = true) {
+    if (value === undefined) {
+        return [];
+    }
+    if (!isUnknownArray(value) || value.length > 32) {
+        throw new Error("Launch roots must contain at most 32 local directories.");
+    }
+    return [
+        ...new Set(value.map((entry) => {
+            const path = absolute(entry, "trusted root");
+            const stat = lstatSync(path);
+            if (!stat.isDirectory() || (owned && stat.uid !== process.getuid?.())) {
+                throw new Error("Launch roots must be owned directories.");
+            }
+            return path;
+        })),
+    ];
+}
+export function within(root, path) {
+    const suffix = relative(root, path);
+    return (suffix !== ".." &&
+        !suffix.startsWith(`..${process.platform === "win32" ? "\\" : "/"}`) &&
+        !isAbsolute(suffix));
+}
+export function launchCwd(policy, requested) {
+    if (!isAbsolute(requested)) {
+        throw new Fault(400, "invalid_cwd", "cwd must be an absolute approved workspace directory.");
+    }
+    let cwd;
+    try {
+        cwd = realpathSync(requested);
+        if (!statSync(cwd).isDirectory()) {
+            throw new Error("Not a directory");
+        }
+    }
+    catch {
+        throw new Fault(400, "invalid_cwd", "cwd must be an existing workspace directory.");
+    }
+    if (!policy.workspaceRoots.some((root) => within(root, cwd))) {
+        throw new Fault(403, "cwd_forbidden", "cwd is outside locally approved workspaceRoots.");
+    }
+    return cwd;
+}
+export function spawnPolicy(policy, input) {
+    if (input.model === undefined) {
+        if (input.provider !== undefined) {
+            throw new Fault(400, "invalid_input", "Spawn provider requires model.");
+        }
+        return policy;
+    }
+    // Native provider/model convention splits at the first slash; model IDs may contain further slashes.
+    const slash = input.model.indexOf("/");
+    const provider = input.provider ?? (slash > 0 ? input.model.slice(0, slash) : policy.provider);
+    const model = input.provider === undefined && slash > 0 ? input.model.slice(slash + 1) : input.model;
+    if (provider === undefined || provider.trim() === "" || model.trim() === "") {
+        throw new Fault(400, "invalid_input", "Use an exact provider/model reference or a provider and model pair.");
+    }
+    return { ...policy, provider: provider.trim(), model: model.trim() };
+}
 export function launchPolicy(value) {
     if (value === undefined) {
         return;
@@ -62,6 +121,8 @@ export function launchPolicy(value) {
         "offline",
         "maxSessions",
         "startupTimeoutMs",
+        "workspaceRoots",
+        "resumeDirs",
     ]);
     const packageRoot = absolute(raw.packageRoot, "Pi package root");
     const sessionDir = absolute(raw.sessionDir, "session directory");
@@ -71,12 +132,17 @@ export function launchPolicy(value) {
         (storage.mode & 0o777) !== 0o700) {
         throw new Error("Launch storage must be an owned directory with mode 0700.");
     }
+    if ((raw.provider === undefined) !== (raw.model === undefined)) {
+        throw new Error("Launch provider and model must both be supplied or both omitted.");
+    }
     return {
         packageRoot,
         cli: executable(packageRoot),
         sessionDir,
-        provider: label(raw.provider, "provider", 128),
-        model: label(raw.model, "model", 256),
+        provider: raw.provider === undefined ? undefined : label(raw.provider, "provider", 128),
+        model: raw.model === undefined ? undefined : label(raw.model, "model", 256),
+        workspaceRoots: directories(raw.workspaceRoots, false),
+        resumeDirs: directories(raw.resumeDirs),
         context: text(raw.context),
         extensions: extensions(raw.extensions),
         discoverResources: boolean(raw.discoverResources, false),