@fitchmultz/pi-subagents 0.45.0 → 0.46.1

package/CHANGELOG.md

@@ -1,5 +1,17 @@
 # Changelog
 
+## [0.46.1] - 2026-10-11
+
+### Fixed
+
+- A child that fails with Node's bare `terminated` network error (the response stream dropped mid-body, common during Wi-Fi drops) now gets the same-model retry and configured fallback models like other transport failures, instead of failing outright. Pi already retries this error inside the child.
+
+## [0.46.0] - 2026-10-11
+
+### Added
+
+- Opt-in controlled destination Pi-session launching over the secure Intercom bridge: locally pinned native RPC sessions, private native journals and inference-free startup, actual peer readiness, name reuse, own-session status/stop, caps, and remote CLI commands. Cancellation, expiry, revocation and shutdown reap the helper-owned process group, including unresponsive native workers, while retaining journals and observing actual closure. Cleanup deadlines report `stop_timeout` and remain retryable; cleanup failures preserve the original startup fault. Messaging-only and standalone credential installs remain independent of Pi SDK imports.
+
 ## [0.45.0] - 2026-10-11
 
 ### Changed

package/README.md

@@ -79,7 +79,7 @@ Children normally inherit Pi's tools, extensions, project instructions and skill
 
 Intercom is included. It lets Pi sessions exchange messages and lets a child ask its parent for a decision.
 
-Read the [Intercom guide](docs/intercom.md) for setup and host limits. The [secure bridge](docs/intercom-bridge.md) supports a remote Linux agent.
+Read the [Intercom guide](docs/intercom.md) for setup and host limits. The [secure bridge](docs/intercom-bridge.md) supports messaging and optional locally controlled Pi-session launches for a remote Linux agent.
 
 Indexed history requires SQLite 3.53.4 through Node's built-in `node:sqlite` binding. Other SQLite versions fail. See the [storage requirements](docs/performance.md#storage-budgets-and-recovery) and [host startup costs](docs/performance.md#necessary-costs-and-limits).
 

package/dist/agents/agent-selection.js

@@ -1,25 +1,13 @@
-export function mergeAgentsForScope(scope, userAgents, projectAgents, builtinAgents = []) {
+export function mergeAgents(userAgents, projectAgents, builtinAgents) {
     const agentMap = new Map();
     for (const agent of builtinAgents) {
         agentMap.set(agent.name, agent);
     }
-    if (scope === "both") {
-        for (const agent of userAgents) {
-            agentMap.set(agent.name, agent);
-        }
-        for (const agent of projectAgents) {
-            agentMap.set(agent.name, agent);
-        }
-    }
-    else if (scope === "user") {
-        for (const agent of userAgents) {
-            agentMap.set(agent.name, agent);
-        }
+    for (const agent of userAgents) {
+        agentMap.set(agent.name, agent);
     }
-    else {
-        for (const agent of projectAgents) {
-            agentMap.set(agent.name, agent);
-        }
+    for (const agent of projectAgents) {
+        agentMap.set(agent.name, agent);
     }
     return Array.from(agentMap.values());
 }

package/dist/agents/agents.js

@@ -9,7 +9,7 @@ import { loadAgentsFromDir, clearAgentDiagnosticsForDirs, agentDiagnosticsForDir
 import { EMPTY_SUBAGENT_SETTINGS, readSubagentSettings, applyBuiltinOverrides, } from "./builtin-overrides.js";
 import { loadConfiguredPackageAgents } from "./package-agents.js";
 import { parseChain, parseJsonChain } from "./chain-serializer.js";
-import { mergeAgentsForScope } from "./agent-selection.js";
+import { mergeAgents } from "./agent-selection.js";
 import { errorMessage } from "./config-values.js";
 export { buildRuntimeName, frontmatterNameForConfig, parsePackageName } from "./identity.js";
 export { defaultSystemPromptMode, defaultInheritProjectContext, defaultInheritSkills, } from "./agent-defaults.js";
@@ -80,7 +80,7 @@ export function discoverAgents(cwd, scope, options = {}) {
     const paths = profilePaths(cwd, options);
     const profiles = discoverLocalProfiles(paths, scope);
     const packages = loadConfiguredPackageAgents(cwd, scope, options);
-    const agents = mergeAgentsForScope(scope, profiles.user, profiles.project, [
+    const agents = mergeAgents(profiles.user, profiles.project, [
         ...profiles.builtin,
         ...packages.agents,
     ]).filter((agent) => agent.disabled !== true);

package/dist/extension/build-info.js

@@ -1 +1 @@
-export const EXTENSION_BUILD = Object.freeze({"version":"0.45.0","sha256":"cfeabcf0312c82d925049312c2368f93a90a8ec6ff1205c1e3122866ef50faac"});
+export const EXTENSION_BUILD = Object.freeze({"version":"0.46.1","sha256":"c04a71cfa57811b1a2d45d43b71aa2edd0f47cd86f3b8ca91730a87ffe854304"});

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

@@ -1,8 +1,9 @@
-import { constants, closeSync, fstatSync, openSync, readFileSync, statSync } from "node:fs";
+import { constants, closeSync, fstatSync, openSync, readFileSync, realpathSync, statSync, } from "node:fs";
 import { isAbsolute } from "node:path";
 import { createSecureContext } from "node:tls";
 import { isUnknownArray } from "../shared/unknown.js";
 import { BODY_LIMIT, object, label, fingerprint } from "./bridge-protocol.js";
+import { launchPolicy } from "./bridge-launch-policy.js";
 const MAX_CLIENTS = 64;
 function readFile(path, privateFile, limit) {
     const fd = openSync(path, constants.O_RDONLY | constants.O_NOFOLLOW);
@@ -31,17 +32,26 @@ function identities(value) {
     const clients = new Map();
     const names = new Set();
     for (const raw of value) {
-        const entry = object(raw, ["fingerprint256", "name", "cwd"]);
+        const entry = object(raw, ["fingerprint256", "name", "cwd", "launch"]);
         const fingerprint256 = fingerprint(entry.fingerprint256);
         const name = label(entry.name, "name", 128).trim();
         const cwd = label(entry.cwd, "cwd", 4096);
-        if (!isAbsolute(cwd) || !statSync(cwd).isDirectory()) {
-            throw new Error("Client cwd must be an existing absolute directory.");
+        if (!isAbsolute(cwd)) {
+            throw new Error("Client cwd must be absolute.");
+        }
+        const launch = launchPolicy(entry.launch);
+        if (launch && !statSync(cwd).isDirectory()) {
+            throw new Error("Launch cwd must be an existing directory.");
         }
         if (clients.has(fingerprint256) || names.has(name.toLowerCase())) {
             throw new Error("Client fingerprints and names must be unique.");
         }
-        clients.set(fingerprint256, { fingerprint256, name, cwd });
+        clients.set(fingerprint256, {
+            fingerprint256,
+            name,
+            cwd: launch ? realpathSync(cwd) : cwd,
+            launch,
+        });
         names.add(name.toLowerCase());
     }
     return clients;

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

@@ -0,0 +1,88 @@
+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";
+function absolute(value, field) {
+    const path = label(value, field, 4096);
+    if (!isAbsolute(path)) {
+        throw new Error(`${field} must be absolute.`);
+    }
+    return realpathSync(path);
+}
+function bounded(value, fallback, max) {
+    const number = value ?? fallback;
+    if (typeof number !== "number" || !Number.isInteger(number) || number < 1 || number > max) {
+        throw new Error("Invalid launch limit.");
+    }
+    return number;
+}
+function boolean(value, fallback) {
+    if (value === undefined) {
+        return fallback;
+    }
+    if (typeof value !== "boolean") {
+        throw new Error("Launch switches must be boolean.");
+    }
+    return value;
+}
+function executable(packageRoot) {
+    const manifest = JSON.parse(readFileSync(join(packageRoot, "package.json"), "utf8"));
+    if (!isRecord(manifest) ||
+        manifest.name !== "@earendil-works/pi-coding-agent" ||
+        !isRecord(manifest.bin)) {
+        throw new Error("Launch package must be an installed Pi package.");
+    }
+    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()) {
+        throw new Error("Pi bin must be a file inside the pinned package.");
+    }
+    return cli;
+}
+function extensions(value) {
+    if (!isUnknownArray(value) || value.length < 1 || value.length > 32) {
+        throw new Error("Launch extensions must contain 1..32 local paths.");
+    }
+    return value.map((entry) => absolute(entry, "extension path"));
+}
+export function launchPolicy(value) {
+    if (value === undefined) {
+        return;
+    }
+    const raw = object(value, [
+        "packageRoot",
+        "sessionDir",
+        "provider",
+        "model",
+        "context",
+        "extensions",
+        "discoverResources",
+        "trustProject",
+        "offline",
+        "maxSessions",
+        "startupTimeoutMs",
+    ]);
+    const packageRoot = absolute(raw.packageRoot, "Pi package root");
+    const sessionDir = absolute(raw.sessionDir, "session directory");
+    const storage = lstatSync(sessionDir);
+    if (!storage.isDirectory() ||
+        storage.uid !== process.getuid?.() ||
+        (storage.mode & 0o777) !== 0o700) {
+        throw new Error("Launch storage must be an owned directory with mode 0700.");
+    }
+    return {
+        packageRoot,
+        cli: executable(packageRoot),
+        sessionDir,
+        provider: label(raw.provider, "provider", 128),
+        model: label(raw.model, "model", 256),
+        context: text(raw.context),
+        extensions: extensions(raw.extensions),
+        discoverResources: boolean(raw.discoverResources, false),
+        trustProject: boolean(raw.trustProject, false),
+        offline: boolean(raw.offline, false),
+        maxSessions: bounded(raw.maxSessions, 4, 16),
+        startupTimeoutMs: bounded(raw.startupTimeoutMs, 15000, 60000),
+    };
+}

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

@@ -0,0 +1,217 @@
+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 { Fault, cancelled, log, wait } from "./bridge-protocol.js";
+import { RpcProcess } from "./bridge-rpc-process.js";
+export function sameIdentity(left, right) {
+    return (left.name === right?.name &&
+        left.cwd === right.cwd &&
+        JSON.stringify(left.launch) === JSON.stringify(right.launch));
+}
+function view(entry) {
+    return {
+        sessionId: entry.sessionId,
+        peerId: entry.peerId,
+        name: entry.name,
+        sessionFile: entry.sessionFile,
+        pid: entry.process?.pid,
+        status: entry.process?.status ?? "starting",
+        error: entry.process?.failure?.code,
+    };
+}
+export class Launcher {
+    launches = new Set();
+    stopping = false;
+    list(identity) {
+        return {
+            sessions: [...this.launches]
+                .filter((entry) => entry.identity.fingerprint256 === identity.fingerprint256)
+                .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.");
+        }
+        await this.retire(entry, new Fault(410, "session_stopped", "Session stopped by its owner."));
+        return { session: view(entry) };
+    }
+    async start(name, 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);
+        }
+        this.capacity(context.identity, policy);
+        const entry = {
+            identity: context.identity,
+            name: fullName,
+            controller: new AbortController(),
+            expires: context.expires,
+            admitted: false,
+        };
+        this.launches.add(entry);
+        try {
+            return await this.establish(entry, policy, context);
+        }
+        catch (error) {
+            await this.retire(entry, new Fault(503, "launch_failed", "Pi startup failed.")).catch(() => log("launch_cleanup", { pid: entry.process?.pid, result: "failed" }));
+            if (!entry.process) {
+                this.launches.delete(entry);
+            }
+            throw error instanceof Fault
+                ? error
+                : new Fault(503, "launch_failed", "Pi startup failed; inspect the pinned local policy and resources.");
+        }
+    }
+    reuse(entry) {
+        if (entry.admitted &&
+            (entry.process?.status === "idle" || entry.process?.status === "running")) {
+            return { session: view(entry), reused: true };
+        }
+        throw new Fault(409, "launch_in_progress", "This named session is starting or stopping; inspect sessions before retrying.");
+    }
+    capacity(identity, policy) {
+        const active = [...this.launches].filter((entry) => entry.process?.status !== "exited");
+        if (active.length >= 32 ||
+            active.filter((entry) => entry.identity.fingerprint256 === identity.fingerprint256).length >=
+                policy.maxSessions) {
+            throw new Fault(429, "session_limit", "Local launched-session capacity reached; stop an owned session first.");
+        }
+        for (const entry of this.launches) {
+            if (this.launches.size >= 64 && entry.process?.status === "exited") {
+                this.launches.delete(entry);
+            }
+        }
+    }
+    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);
+            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);
+            this.expiry(entry);
+            const state = await entry.process.state(signal);
+            this.validateState(entry, policy, state);
+            await this.peerReady(entry, context.peers, signal);
+            cancelled(signal);
+            entry.process.ready();
+            entry.admitted = true;
+            log("launch_ready", {
+                fingerprint: entry.identity.fingerprint256,
+                name: entry.name,
+                peer: entry.peerId,
+                pid: entry.process.pid,
+                result: "ready",
+            });
+            return { session: view(entry), 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.
+            // 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)) {
+                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 });
+        }
+        throw entry.process.failure;
+    }
+    expiry(entry) {
+        const expire = () => {
+            if (entry.expires <= Date.now()) {
+                this.retire(entry, new Fault(403, "certificate_expired", "Launch owner's certificate expired.")).catch(() => log("launch_cleanup", { result: "failed" }));
+            }
+            else {
+                entry.timer = setTimeout(expire, Math.min(entry.expires - Date.now(), 0x7fffffff));
+            }
+        };
+        expire();
+        entry.process?.exited
+            .then(() => clearTimeout(entry.timer))
+            .catch(() => log("launch_cleanup", { result: "failed" }));
+    }
+    async retire(entry, fault) {
+        entry.controller.abort(fault);
+        clearTimeout(entry.timer);
+        await entry.process?.stop();
+    }
+    async revoke(clients) {
+        await Promise.all([...this.launches]
+            .filter((entry) => !sameIdentity(entry.identity, clients.get(entry.identity.fingerprint256)))
+            .map((entry) => this.retire(entry, new Fault(403, "revoked", "Launch owner's identity or policy was revoked."))));
+    }
+    async shutdown() {
+        this.stopping = true;
+        await Promise.all([...this.launches].map((entry) => this.retire(entry, new Fault(503, "shutting_down", "Bridge is shutting down."))));
+    }
+}

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

@@ -9,6 +9,9 @@ const fields = {
     "POST /v1/send": ["to", "message"],
     "POST /v1/ask": ["to", "message", "timeoutMs"],
     "POST /v1/reply": ["replyTo", "message"],
+    "POST /v1/start": ["name"],
+    "GET /v1/sessions": [],
+    "POST /v1/stop": ["sessionId"],
 };
 function isRoute(route) {
     return Object.hasOwn(fields, route);
@@ -42,7 +45,12 @@ export async function operationFor(req, route, signal) {
         case "GET /v1/list":
         case "GET /v1/inbox":
         case "POST /v1/register":
+        case "GET /v1/sessions":
             return { route };
+        case "POST /v1/start":
+            return { route, name: label(input.name, "session name", 64).trim() };
+        case "POST /v1/stop":
+            return { route, sessionId: label(input.sessionId, "session ID", 128) };
         case "POST /v1/ack": {
             if (!isUnknownArray(input.ids) || input.ids.length > INBOX_COUNT) {
                 throw new Fault(400, "invalid_input", "ids must be an array of at most 256 message IDs.");