@fitchmultz/pi-subagents 0.47.0 → 0.48.0

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

@@ -1,10 +1,12 @@
-import { createHash } from "node:crypto";
-import { statSync } from "node:fs";
 import { setTimeout as delay } from "node:timers/promises";
-import { loadNativeSession } from "../shared/native-session-loader.js";
 import { isRecord } from "../shared/unknown.js";
+import { launchCwd, spawnPolicy } from "./bridge-launch-policy.js";
 import { Fault, cancelled, log, wait } from "./bridge-protocol.js";
 import { RpcProcess } from "./bridge-rpc-process.js";
+import { exactPeer, savedView, browseSessions, } from "./bridge-catalog.js";
+import { createLaunchJournal, resumeLaunchJournal, validateLaunchState, } from "./bridge-launch-journal.js";
+import { spawnBrokerIfNeeded } from "./broker/spawn.js";
+import { resolveIntercomPresenceName } from "./identity.js";
 export function sameIdentity(left, right) {
     return (left.name === right?.name &&
         left.cwd === right.cwd &&
@@ -12,18 +14,27 @@ export function sameIdentity(left, right) {
 }
 function view(entry) {
     return {
-        sessionId: entry.sessionId,
-        peerId: entry.peerId,
+        id: entry.journal?.sessionId,
+        sessionId: entry.journal?.sessionId,
+        peerId: entry.journal?.peerId,
         name: entry.name,
-        sessionFile: entry.sessionFile,
+        cwd: entry.cwd,
+        sessionFile: entry.journal?.sessionFile,
         pid: entry.process?.pid,
         status: entry.process?.status ?? "starting",
         error: entry.process?.failure?.code,
+        saved: entry.journal !== undefined,
+        owned: true,
     };
 }
 export class Launcher {
     launches = new Set();
+    catalog;
+    resuming = new Set();
     stopping = false;
+    constructor(catalog) {
+        this.catalog = catalog;
+    }
     list(identity) {
         return {
             sessions: [...this.launches]
@@ -31,36 +42,175 @@ export class Launcher {
                 .map(view),
         };
     }
-    async stop(identity, sessionId) {
-        const entry = [...this.launches].find((candidate) => candidate.identity.fingerprint256 === identity.fingerprint256 &&
-            candidate.sessionId === sessionId);
-        if (!entry) {
-            throw new Fault(404, "unknown_session", "Session is not owned by this identity and helper.");
+    async browse(query, context) {
+        return browseSessions(this.catalog, query, {
+            policy: context.identity.launch,
+            signal: context.signal,
+            peers: context.peers,
+            activeState: (id) => {
+                const entry = this.active(id) ?? this.activePeer(id);
+                return entry?.identity.fingerprint256 === context.identity.fingerprint256
+                    ? (entry.process?.status ?? "starting")
+                    : undefined;
+            },
+        });
+    }
+    active(sessionId) {
+        return [...this.launches].find((entry) => entry.journal?.sessionId === sessionId && entry.process?.status !== "exited");
+    }
+    activePeer(peerId) {
+        return [...this.launches].find((entry) => entry.journal?.peerId === peerId && entry.process?.status !== "exited");
+    }
+    async owned(identity, id, context) {
+        const candidates = [...this.launches].filter((candidate) => candidate.identity.fingerprint256 === identity.fingerprint256);
+        const byId = candidates.findLast((candidate) => candidate.journal?.sessionId === id || candidate.journal?.peerId === id);
+        const named = candidates.filter((candidate) => candidate.process?.status !== "exited" &&
+            (candidate.name === id || candidate.name === `remote:${identity.name}:${id}`));
+        if (!byId && named.length > 1) {
+            throw new Fault(409, "ambiguous_session", "Multiple owned live processes match this name; use their native IDs.");
+        }
+        const entry = byId ?? named.at(0);
+        if (!entry?.process) {
+            throw new Fault(404, "unknown_session", "Control is available only for this identity's helper-owned subprocesses, not unrelated live peers or saved history.");
+        }
+        if (entry.process.status === "exited") {
+            const peers = await context.peers(context.signal);
+            if (peers.some((peer) => peer.id === entry.journal?.peerId)) {
+                throw new Fault(404, "unknown_session", "This journal has a newer live owner; the historical process is not current ownership.");
+            }
         }
+        return entry;
+    }
+    async stop(identity, sessionId, context) {
+        const entry = await this.owned(identity, sessionId, context);
         await this.retire(entry, new Fault(410, "session_stopped", "Session stopped by its owner."));
         return { session: view(entry) };
     }
+    async cancel(identity, sessionId, context) {
+        const entry = await this.owned(identity, sessionId, context);
+        if (!entry.admitted || entry.process?.status === "exited" || !entry.process) {
+            throw new Fault(409, "session_not_ready", "Only an admitted live owned session can be cancelled.");
+        }
+        const state = await entry.process.cancel(context.signal);
+        return { session: view(entry), cancelled: true, state, queuesPreserved: true };
+    }
     async start(name, context) {
+        return this.spawn({ name }, context, true);
+    }
+    async spawn(input, context, legacy = false) {
+        const policy = spawnPolicy(this.policy(context), input);
+        const cwd = legacy
+            ? context.identity.cwd
+            : launchCwd(policy, input.cwd ?? context.identity.cwd);
+        const name = `remote:${context.identity.name}:${input.name}`;
+        const existing = [...this.launches].find((entry) => entry.identity.fingerprint256 === context.identity.fingerprint256 &&
+            entry.name === name &&
+            entry.process?.status !== "exited");
+        const result = existing
+            ? this.reuseSpawn(existing, input, policy, cwd)
+            : await this.launch({ name, cwd }, context, policy);
+        return this.task(result, input.task, context);
+    }
+    reuseSpawn(entry, input, policy, cwd) {
+        if (entry.cwd !== cwd) {
+            throw new Fault(409, "cwd_conflict", "This live name already belongs to a different workspace.");
+        }
+        if (input.model !== undefined &&
+            (entry.journal?.model?.provider !== policy.provider ||
+                entry.journal?.model?.modelId !== policy.model)) {
+            throw new Fault(409, "model_conflict", "This live name already belongs to a different model selection; resume it without overriding history.");
+        }
+        return this.reuse(entry);
+    }
+    async resume(input, context) {
+        const policy = this.policy(context);
+        const selector = input.sessionId ?? input.target ?? `name:${input.name ?? ""}`;
+        if (this.resuming.has(selector)) {
+            throw new Fault(409, "launch_in_progress", "This resume selector is already starting.");
+        }
+        this.resuming.add(selector);
+        try {
+            const saved = await this.catalog.resolve(policy, input, context.signal);
+            launchCwd(policy, saved.cwd);
+            const owned = this.active(saved.sessionId);
+            if (owned) {
+                const result = this.reuse(owned);
+                const reused = owned.identity.fingerprint256 === context.identity.fingerprint256
+                    ? result
+                    : {
+                        ...result,
+                        session: {
+                            ...savedView(saved),
+                            peerId: saved.peerId,
+                            status: owned.process?.status,
+                        },
+                    };
+                return await this.task(reused, input.task, context);
+            }
+            await wait(spawnBrokerIfNeeded(process.execPath, []), context.signal);
+            const peer = exactPeer(saved, await context.peers(context.signal));
+            if (peer) {
+                return await this.task({ session: savedView(saved, peer), id: saved.sessionId, reused: true }, input.task, context);
+            }
+            // A different selector/identity may have completed catalog resolution during the peer lookup.
+            if (this.active(saved.sessionId)) {
+                throw new Fault(409, "launch_in_progress", "This native session is already starting.");
+            }
+            const result = await this.launch(saved, context, policy);
+            return await this.task(result, input.task, context);
+        }
+        finally {
+            this.resuming.delete(selector);
+        }
+    }
+    policy(context) {
         cancelled(context.signal);
         const policy = context.identity.launch;
         if (!policy || this.stopping) {
             throw new Fault(403, "launch_disabled", "Session launching is not enabled by local policy.");
         }
-        const fullName = `remote:${context.identity.name}:${name}`;
-        const existing = [...this.launches].find((entry) => entry.identity.fingerprint256 === context.identity.fingerprint256 &&
-            entry.name === fullName &&
-            entry.process?.status !== "exited");
-        if (existing) {
-            return this.reuse(existing);
+        return policy;
+    }
+    async task(result, task, context) {
+        const session = result.session;
+        if (task === undefined || !isRecord(session) || typeof session.peerId !== "string") {
+            return result;
+        }
+        try {
+            const receipt = await context.submit(session.peerId, task);
+            return { ...result, id: session.sessionId, task: { ...receipt, completed: false } };
+        }
+        catch (error) {
+            const fault = error instanceof Fault
+                ? error
+                : new Fault(503, "task_unconfirmed", "Task acceptance is unknown; inspect the session before retrying.");
+            throw new Fault(fault.status, fault.code, fault.message, {
+                ...fault.details,
+                session,
+                reused: result.reused,
+            });
         }
+    }
+    async launch(target, context, policy) {
         this.capacity(context.identity, policy);
         const entry = {
             identity: context.identity,
-            name: fullName,
+            name: target.name,
+            cwd: target.cwd,
             controller: new AbortController(),
             expires: context.expires,
             admitted: false,
         };
+        if (target.sessionId !== undefined &&
+            target.peerId !== undefined &&
+            target.sessionFile !== undefined) {
+            entry.journal = {
+                ...target,
+                sessionId: target.sessionId,
+                peerId: target.peerId,
+                sessionFile: target.sessionFile,
+            };
+        }
         this.launches.add(entry);
         try {
             return await this.establish(entry, policy, context);
@@ -72,15 +222,15 @@ export class Launcher {
             }
             throw error instanceof Fault
                 ? error
-                : new Fault(503, "launch_failed", "Pi startup failed; inspect the pinned local policy and resources.");
+                : new Fault(503, "launch_failed", "Pi startup failed; inspect local policy and resources.");
         }
     }
     reuse(entry) {
         if (entry.admitted &&
             (entry.process?.status === "idle" || entry.process?.status === "running")) {
-            return { session: view(entry), reused: true };
+            return { session: view(entry), id: entry.journal?.sessionId, reused: true };
         }
-        throw new Fault(409, "launch_in_progress", "This named session is starting or stopping; inspect sessions before retrying.");
+        throw new Fault(409, "launch_in_progress", "This session is starting or stopping; inspect sessions before retrying.");
     }
     capacity(identity, policy) {
         const active = [...this.launches].filter((entry) => entry.process?.status !== "exited");
@@ -95,52 +245,23 @@ export class Launcher {
             }
         }
     }
-    async journal(entry, policy) {
-        const { SessionManager } = await wait(loadNativeSession(policy.packageRoot), entry.controller.signal);
-        cancelled(entry.controller.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 = SessionManager.create(entry.identity.cwd, policy.sessionDir);
-            manager.appendSessionInfo(entry.name);
-            manager.appendMessage({ role: "user", content: policy.context, timestamp: Date.now() });
-            entry.sessionId = manager.getSessionId();
-            entry.sessionFile = manager.getSessionFile();
-            entry.peerId = `pi-${createHash("sha256").update(entry.sessionId).digest("hex").slice(0, 32)}`;
-            if (entry.sessionFile === undefined || (statSync(entry.sessionFile).mode & 0o777) !== 0o600) {
-                throw new Fault(503, "journal_invalid", "Native journal was not privately persisted.");
-            }
-            const saved = SessionManager.open(entry.sessionFile, policy.sessionDir);
-            if (saved.getSessionId() !== entry.sessionId ||
-                saved.getSessionName() !== entry.name ||
-                saved.getCwd() !== entry.identity.cwd) {
-                throw new Fault(503, "journal_invalid", "Native journal identity did not persist.");
-            }
-        }
-        finally {
-            process.umask(previous);
-        }
-    }
     async establish(entry, policy, context) {
         const signal = AbortSignal.any([context.signal, entry.controller.signal]);
         const deadline = setTimeout(() => entry.controller.abort(new Fault(504, "launch_timeout", "Pi startup readiness deadline exceeded.")), policy.startupTimeoutMs);
         const abort = () => entry.controller.abort(new Fault(499, "launch_cancelled", "Session startup cancelled or exceeded its deadline."));
         signal.addEventListener("abort", abort, { once: true });
         try {
-            await this.journal(entry, policy);
+            const resuming = entry.journal !== undefined;
+            entry.journal = entry.journal
+                ? await resumeLaunchJournal(policy, entry.journal, signal)
+                : await createLaunchJournal(policy, { cwd: entry.cwd, name: entry.name ?? "" }, signal);
             cancelled(signal);
-            if (entry.sessionFile === undefined) {
-                throw new Fault(503, "journal_invalid", "Native journal path unavailable.");
-            }
-            entry.process = new RpcProcess(policy, entry.identity.cwd, entry.sessionFile);
+            entry.process = new RpcProcess(policy, entry.cwd, entry.journal.sessionFile, resuming);
             this.expiry(entry);
-            const state = await entry.process.state(signal);
-            this.validateState(entry, policy, state);
+            validateLaunchState(entry.journal, await entry.process.state(signal));
+            await wait(spawnBrokerIfNeeded(process.execPath, []).catch(() => {
+                throw new Fault(503, "broker_unavailable", "Local broker could not be acquired safely.");
+            }), signal);
             await this.peerReady(entry, context.peers, signal);
             cancelled(signal);
             entry.process.ready();
@@ -148,39 +269,28 @@ export class Launcher {
             log("launch_ready", {
                 fingerprint: entry.identity.fingerprint256,
                 name: entry.name,
-                peer: entry.peerId,
+                peer: entry.journal.peerId,
                 pid: entry.process.pid,
                 result: "ready",
             });
-            return { session: view(entry), reused: false };
+            return { session: view(entry), id: entry.journal.sessionId, reused: false };
         }
         finally {
             clearTimeout(deadline);
             signal.removeEventListener("abort", abort);
         }
     }
-    validateState(entry, policy, state) {
-        if (state.sessionId !== entry.sessionId ||
-            state.sessionFile !== entry.sessionFile ||
-            state.sessionName !== entry.name ||
-            state.isStreaming !== false ||
-            state.pendingMessageCount !== 0 ||
-            !isRecord(state.model) ||
-            state.model.provider !== policy.provider ||
-            state.model.id !== policy.model) {
-            throw new Fault(503, "readiness_failed", "Pi did not start idle with the exact saved session and configured model.");
-        }
-    }
     async peerReady(entry, peers, signal) {
         while (!entry.process?.failure) {
             cancelled(signal);
-            // Registration is asynchronous after native session_start; observe real broker publication.
+            // Native startup alone is insufficient: observe the exact Intercom publication.
             // oxlint-disable-next-line no-await-in-loop
             const rows = await peers(signal);
-            if (rows.some((peer) => peer.id === entry.peerId && peer.name === entry.name && peer.cwd === entry.identity.cwd)) {
+            if (rows.some((peer) => peer.id === entry.journal?.peerId &&
+                peer.name === resolveIntercomPresenceName(entry.name, entry.journal.sessionId) &&
+                peer.cwd === entry.cwd)) {
                 return;
             }
-            // Bounded readiness polling is not an acknowledgement substitute; only the row above succeeds.
             // oxlint-disable-next-line no-await-in-loop
             await delay(100, undefined, { signal });
         }

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

@@ -0,0 +1,127 @@
+import { join } from "node:path";
+import { isRecord } from "../shared/unknown.js";
+import { Launcher } from "./bridge-launch.js";
+import { SessionCatalog, savedView, trustedJournal } from "./bridge-catalog.js";
+import { Groups } from "./bridge-groups.js";
+import { broadcastTargets } from "./bridge-broadcast.js";
+import { getPiAgentDir } from "./agent-dir.js";
+import { Fault } from "./bridge-protocol.js";
+import { resolveBridgeTarget } from "./bridge-target.js";
+import { readSavedTranscript } from "./saved-transcript.js";
+/** Request operations own launch/catalog/group state; transport owns admission and cancellation. */
+export class BridgeOperations {
+    catalog = new SessionCatalog();
+    launcher = new Launcher(this.catalog);
+    stateDir;
+    groups;
+    constructor(stateDir) {
+        this.stateDir = stateDir ?? join(getPiAgentDir(), "intercom", "bridge-state");
+    }
+    revoke(clients) {
+        return this.launcher.revoke(clients);
+    }
+    shutdown() {
+        return this.launcher.shutdown();
+    }
+    groupStore() {
+        this.groups ??= new Groups(this.stateDir);
+        return this.groups;
+    }
+    async execute(operation, session, context) {
+        const launchContext = {
+            identity: session.identity,
+            expires: context.expires,
+            signal: context.signal,
+            peers: (signal) => session.connectedPeers(signal),
+            submit: (peer, task) => session.send(peer, task, context),
+        };
+        switch (operation.route) {
+            case "POST /v1/start":
+                return this.launcher.start(operation.name, launchContext);
+            case "POST /v1/spawn":
+                return this.launcher.spawn(operation, launchContext);
+            case "POST /v1/resume":
+                return this.launcher.resume(operation, launchContext);
+            case "GET /v1/sessions":
+                return operation.query === undefined
+                    ? this.launcher.list(session.identity)
+                    : this.launcher.browse(operation.query, launchContext);
+            case "POST /v1/stop":
+            case "POST /v1/cancel":
+                return this.stop(operation, session, context);
+            case "GET /v1/groups":
+                return { groups: this.groupStore().list(session.identity.fingerprint256) };
+            case "POST /v1/groups":
+                return {
+                    groups: this.groupStore().upsert(session.identity.fingerprint256, operation.group),
+                };
+            case "POST /v1/broadcast":
+                return broadcastTargets(session, this.groupStore().targets(session.identity.fingerprint256, operation.group, await session.connectedPeers(context.signal)), operation.message, context);
+            case "POST /v1/control":
+                return session.nativeControl(operation, context.certificate, context);
+            case "GET /v1/transcript":
+                return this.transcript(operation, session, context);
+            case "GET /v1/inbox":
+            case "GET /v1/list":
+            case "POST /v1/ack":
+            case "POST /v1/ask":
+            case "POST /v1/register":
+            case "POST /v1/reply":
+            case "POST /v1/send":
+                return session.execute(operation, context);
+        }
+    }
+    async stop(operation, session, context) {
+        const cancel = operation.route === "POST /v1/cancel";
+        const control = {
+            signal: context.signal,
+            peers: (signal) => session.connectedPeers(signal),
+        };
+        try {
+            return cancel
+                ? await this.launcher.cancel(session.identity, operation.sessionId, control)
+                : await this.launcher.stop(session.identity, operation.sessionId, control);
+        }
+        catch (error) {
+            // Only a pre-effect ownership miss may dispatch elsewhere; never retry an unknown outcome.
+            if (!(error instanceof Fault) || error.code !== "unknown_session") {
+                throw error;
+            }
+        }
+        return session.nativeControl({ to: operation.sessionId, verb: cancel ? "cancel" : "stop", timeoutMs: operation.timeoutMs }, context.certificate, context);
+    }
+    async transcript(operation, session, context) {
+        const peers = await session.connectedPeers(context.signal);
+        try {
+            const peer = resolveBridgeTarget(peers, operation.target, null);
+            const result = await session.nativeControl({
+                to: peer.id,
+                verb: "transcript",
+                options: operation.options,
+                timeoutMs: operation.timeoutMs,
+            }, context.certificate, context);
+            return {
+                ...result,
+                source: "live",
+                transcript: isRecord(result.native) ? result.native.transcript : undefined,
+            };
+        }
+        catch (error) {
+            if (!(error instanceof Fault) || error.code !== "peer_offline") {
+                throw error;
+            }
+        }
+        const policy = session.identity.launch;
+        if (!policy) {
+            throw new Fault(403, "launch_disabled", "Saved transcripts require local resume policy.");
+        }
+        const saved = await this.catalog.resolve(policy, { target: operation.target }, context.signal);
+        trustedJournal(policy, saved.sessionFile);
+        const page = await readSavedTranscript(policy.packageRoot, saved.sessionFile, operation.options);
+        session.guard(context.signal);
+        if (page.sessionId !== saved.sessionId) {
+            throw new Fault(409, "session_changed", "Saved journal identity changed during reading.");
+        }
+        return { status: "ok", source: "saved", session: savedView(saved), transcript: page };
+    }
+}

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

@@ -14,6 +14,13 @@ export class Fault extends Error {
         this.details = details;
     }
 }
+export class BroadcastFault extends Fault {
+    outcome;
+    constructor(fault, outcome) {
+        super(fault.status, fault.code, fault.message, fault.details);
+        this.outcome = { ...outcome, status: "partial" };
+    }
+}
 export function object(value, fields) {
     if (!isRecord(value)) {
         throw new Fault(400, "invalid_input", "Expected a JSON object.");