@selesai/code 0.13.39 → 0.13.40

package/dist/modes/rpc/release-bridge.js

@@ -0,0 +1,159 @@
+import { RELEASE_READINESS_EVENT, STOP_ALL_BACKGROUND_EVENT, STOP_ALL_BACKGROUND_TIMEOUT_MS, decideRelease, isReleaseBlocker, isStopAllBackgroundItem, stopAllContributorError, } from "../../core/release-rpc.js";
+const MAX_BLOCKERS_PER_CONTRIBUTOR = 64;
+const MAX_BLOCKERS = 256;
+const MAX_STOPPED_PER_CONTRIBUTOR = 128;
+const MAX_STOPPED = 512;
+/** Shared by `release_readiness`, `release` and `stop_all_background`: version 1, no unknown keys, bounded single-line id. Returns the error text, if any. */
+export function validateReleaseCommand(command) {
+    const type = command.type;
+    if (command.version !== 1)
+        return `Unsupported ${type} version; expected 1`;
+    if (Object.keys(command).some(key => !["type", "version", "id"].includes(key))
+        || command.id !== undefined && (typeof command.id !== "string" || command.id.length > 128 || /[\r\n]/.test(command.id)))
+        return `Malformed ${type} command`;
+    return undefined;
+}
+/**
+ * Collects release blockers from every extension listener on one host binding. Synchronous and fail closed:
+ * malformed or throwing contributors become `contributor_error` blockers, never silent "safe".
+ */
+export class RpcReleaseBridge {
+    disposed = false;
+    bus;
+    scope;
+    constructor(bus, scope) { this.bus = bus; this.scope = scope; }
+    request(command, coreBlockers = []) {
+        const collected = this.collect(command, coreBlockers);
+        if (typeof collected === "string")
+            return { id: command.id, type: "response", command: command.type, success: false, error: collected };
+        return { id: command.id, type: "response", command: "release_readiness", success: true, data: collected };
+    }
+    /**
+     * Atomic release decision (`release`): validates like `request`, collects readiness and, only when it permits release
+     * (`decideRelease`), calls `commit` before returning. Everything here is synchronous, so nothing can interleave between the
+     * check and the commitment; the caller's `commit` must therefore also be synchronous (set the "releasing" flag).
+     * Not releasable: nothing is committed and the process keeps running.
+     */
+    release(command, coreBlockers, commit) {
+        const collected = this.collect(command, coreBlockers);
+        if (typeof collected === "string")
+            return { id: command.id, type: "response", command: command.type, success: false, error: collected };
+        const released = decideRelease(collected);
+        if (released)
+            commit(collected);
+        return { id: command.id, type: "response", command: "release", success: true, data: { released, readiness: collected } };
+    }
+    /**
+     * Kill switch (`stop_all_background`). Validates like `request`, then starts the core stop and broadcasts
+     * `STOP_ALL_BACKGROUND_EVENT` so every extension starts its own stop synchronously, and awaits all of them under ONE total
+     * budget (`timeoutMs`). A contributor that throws, rejects or is still running at the deadline becomes an `ok:false` item;
+     * it never prevents the others from running or the response from being sent. `remaining` is the readiness collected AFTER
+     * the stop. `success:false` only for a malformed request or a disposed binding.
+     */
+    async stopAll(command, coreStop, coreBlockers, timeoutMs = STOP_ALL_BACKGROUND_TIMEOUT_MS) {
+        const invalid = validateReleaseCommand(command);
+        if (invalid)
+            return { id: command.id, type: "response", command: command.type, success: false, error: invalid };
+        if (this.disposed)
+            return { id: command.id, type: "response", command: command.type, success: false, error: "Release readiness session ended" };
+        const deadline = Date.now() + timeoutMs;
+        const slots = [];
+        let open = true;
+        const add = (name, work) => {
+            if (!open)
+                return; // late (async) registrations cannot cross this request
+            const who = typeof name === "string" && name.length > 0 && name.length <= 64 ? name : "unknown";
+            const slot = { who, settled: Promise.resolve() };
+            const accept = (items) => {
+                if (!open)
+                    return;
+                if (!Array.isArray(items)) {
+                    slot.items = [{ source: who, kind: "contributor", detail: "Malformed stop contribution", ok: false, error: "malformed" }];
+                    return;
+                }
+                const valid = [];
+                for (const item of items.slice(0, MAX_STOPPED_PER_CONTRIBUTOR)) {
+                    valid.push(isStopAllBackgroundItem(item) ? item : { source: who, kind: "contributor", detail: "Malformed stop item", ok: false, error: "malformed" });
+                }
+                if (items.length > MAX_STOPPED_PER_CONTRIBUTOR)
+                    valid.push({ source: who, kind: "contributor", detail: `${items.length - MAX_STOPPED_PER_CONTRIBUTOR} further items omitted`, ok: false, error: "truncated" });
+                slot.items = valid;
+            };
+            slot.settled = Promise.resolve(work).then(accept, (error) => { if (open)
+                slot.items = [stopAllContributorError(who, error)]; });
+            slots.push(slot);
+        };
+        try {
+            add("core", coreStop());
+        }
+        catch (error) {
+            add("core", [stopAllContributorError("core", error)]);
+        }
+        const request = { version: 1, sessionId: this.scope.sessionId, deadline, contribute: add };
+        try {
+            this.bus?.emit(STOP_ALL_BACKGROUND_EVENT, request);
+        }
+        catch (error) {
+            add("unknown", [stopAllContributorError("unknown", error)]);
+        }
+        let timer;
+        const expired = new Promise((resolve) => { timer = setTimeout(resolve, Math.max(0, deadline - Date.now()) + 250); });
+        try {
+            await Promise.race([Promise.all(slots.map((slot) => slot.settled)), expired]);
+        }
+        finally {
+            clearTimeout(timer);
+        }
+        open = false;
+        const stopped = [];
+        for (const slot of slots) {
+            stopped.push(...(slot.items ?? [{ source: slot.who, kind: "contributor", detail: `${slot.who} did not finish stopping within ${timeoutMs}ms`, ok: false, error: "timeout" }]));
+        }
+        const bounded = stopped.slice(0, MAX_STOPPED);
+        if (stopped.length > MAX_STOPPED)
+            bounded.push({ source: "core", kind: "contributor", detail: `${stopped.length - MAX_STOPPED} further items omitted`, ok: false, error: "truncated" });
+        const remaining = this.collect(command, coreBlockers());
+        if (typeof remaining === "string")
+            return { id: command.id, type: "response", command: command.type, success: false, error: remaining };
+        return { id: command.id, type: "response", command: "stop_all_background", success: true, data: { ...this.scope, stopped: bounded, remaining } };
+    }
+    /** Validation error text, or the collected readiness. */
+    collect(command, coreBlockers) {
+        const invalid = validateReleaseCommand(command);
+        if (invalid)
+            return invalid;
+        if (this.disposed)
+            return "Release readiness session ended";
+        const blockers = [...coreBlockers];
+        const contributors = [];
+        let open = true;
+        const request = { version: 1, sessionId: this.scope.sessionId, contribute: (name, contributed) => {
+                if (!open)
+                    return; // late (async) answers cannot cross this request
+                const who = typeof name === "string" && name.length > 0 && name.length <= 64 ? name : "unknown";
+                if (!contributors.includes(who))
+                    contributors.push(who);
+                if (!Array.isArray(contributed)) {
+                    blockers.push({ source: who, kind: "contributor_error", detail: "Malformed release readiness contribution" });
+                    return;
+                }
+                for (const blocker of contributed.slice(0, MAX_BLOCKERS_PER_CONTRIBUTOR)) {
+                    blockers.push(isReleaseBlocker(blocker) ? blocker : { source: who, kind: "contributor_error", detail: "Malformed release blocker" });
+                }
+                if (contributed.length > MAX_BLOCKERS_PER_CONTRIBUTOR)
+                    blockers.push({ source: who, kind: "contributor_error", detail: `${contributed.length - MAX_BLOCKERS_PER_CONTRIBUTOR} further blockers omitted` });
+            } };
+        try {
+            this.bus?.emit(RELEASE_READINESS_EVENT, request);
+        }
+        catch (error) {
+            blockers.push({ source: "unknown", kind: "contributor_error", detail: error?.message?.slice(0, 512) || "release readiness broadcast failed" });
+        }
+        open = false;
+        const bounded = blockers.slice(0, MAX_BLOCKERS);
+        if (blockers.length > MAX_BLOCKERS)
+            bounded.push({ source: "core", kind: "contributor_error", detail: `${blockers.length - MAX_BLOCKERS} further blockers omitted` });
+        return { ...this.scope, safe: bounded.length === 0, blockers: bounded, contributors };
+    }
+    dispose() { this.disposed = true; this.bus = undefined; }
+}

package/dist/modes/rpc/release-bridge.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/modes/rpc/release-bridge.test.js

@@ -0,0 +1,347 @@
+import { describe, expect, it } from "vitest";
+import { createEventBus } from "../../core/event-bus.js";
+import { RELEASE_READINESS_EVENT, STOP_ALL_BACKGROUND_EVENT, answerReleaseReadiness, answerStopAllBackground, decideRelease, isReleaseBlocker, isStopAllBackgroundItem, } from "../../core/release-rpc.js";
+import { RpcReleaseBridge, validateReleaseCommand } from "./release-bridge.js";
+const scope = { version: 1, sessionId: "host", epoch: "bind-1" };
+const command = { type: "release_readiness", version: 1 };
+const blocker = (source, kind, extra = {}) => ({ source, kind, detail: `${kind} detail`, ...extra });
+function data(reply) {
+    if (!reply.success || reply.command !== "release_readiness")
+        throw new Error(JSON.stringify(reply));
+    return reply.data;
+}
+/** Registers a contributor that follows the documented gate (same helper the extensions use). */
+function contributor(bus, name, boundSessionId, compute) {
+    return bus.on(RELEASE_READINESS_EVENT, raw => answerReleaseReadiness(raw, name, boundSessionId, compute));
+}
+describe("RpcReleaseBridge", () => {
+    it("is safe with no contributors and reports who answered", () => {
+        const bridge = new RpcReleaseBridge(undefined, scope);
+        expect(data(bridge.request({ ...command, id: "r" }))).toEqual({ ...scope, safe: true, blockers: [], contributors: [] });
+        expect(bridge.request({ ...command, id: "r" })).toMatchObject({ id: "r", type: "response", command: "release_readiness", success: true });
+    });
+    it("merges core blockers and many contributors, and answers safe when all are empty", () => {
+        const bus = createEventBus();
+        contributor(bus, "subagents", "host", () => [blocker("subagents", "async_run", { id: "run-1", since: 5 })]);
+        contributor(bus, "intercom", "host", () => [blocker("intercom", "inbound_ask", { id: "m1" }), blocker("intercom", "outbound_ask")]);
+        contributor(bus, "scheduler", "host", () => []);
+        const bridge = new RpcReleaseBridge(bus, scope);
+        const busy = data(bridge.request(command, [blocker("core", "streaming")]));
+        expect(busy.safe).toBe(false);
+        expect(busy.contributors).toEqual(["subagents", "intercom", "scheduler"]);
+        expect(busy.blockers.map(b => `${b.source}:${b.kind}`)).toEqual(["core:streaming", "subagents:async_run", "intercom:inbound_ask", "intercom:outbound_ask"]);
+        expect(busy).toMatchObject({ ...scope });
+        const idleBus = createEventBus();
+        contributor(idleBus, "subagents", "host", () => []);
+        contributor(idleBus, "scheduler", "host", () => []);
+        expect(data(new RpcReleaseBridge(idleBus, scope).request(command))).toMatchObject({ safe: true, blockers: [], contributors: ["subagents", "scheduler"] });
+    });
+    it("turns a throwing contributor into a contributor_error blocker without crashing", async () => {
+        const bus = createEventBus();
+        const quiet = () => undefined;
+        const original = console.error;
+        console.error = quiet;
+        try {
+            contributor(bus, "subagents", "host", () => { throw new Error("status.json is corrupt"); });
+            // A raw listener that bypasses the helper: the bus swallows its exception, but it must not make the result safe-by-accident
+            // when other contributors answered; here it simply does not contribute.
+            bus.on(RELEASE_READINESS_EVENT, () => { throw new Error("raw listener exploded"); });
+            const result = data(new RpcReleaseBridge(bus, scope).request(command));
+            expect(result.safe).toBe(false);
+            expect(result.contributors).toEqual(["subagents"]);
+            expect(result.blockers).toEqual([{ source: "subagents", kind: "contributor_error", detail: "status.json is corrupt" }]);
+            await new Promise(done => setTimeout(done, 0)); // let the bus log the raw listener's swallowed error while console.error is muted
+        }
+        finally {
+            console.error = original;
+        }
+    });
+    it("fails closed when a bus emit throws or a contribution is malformed", () => {
+        const throwing = { emit() { throw new Error("bus down"); }, on: () => () => undefined };
+        expect(data(new RpcReleaseBridge(throwing, scope).request(command))).toMatchObject({ safe: false, blockers: [{ source: "unknown", kind: "contributor_error", detail: "bus down" }] });
+        const bus = createEventBus();
+        bus.on(RELEASE_READINESS_EVENT, raw => {
+            const request = raw;
+            request.contribute("bad-shape", "nope");
+            request.contribute("bad-blocker", [{ source: "x", kind: "", detail: "" }, blocker("bad-blocker", "ok")]);
+            request.contribute("", []);
+        });
+        const result = data(new RpcReleaseBridge(bus, scope).request(command));
+        expect(result.safe).toBe(false);
+        expect(result.contributors).toEqual(["bad-shape", "bad-blocker", "unknown"]);
+        expect(result.blockers.filter(b => b.kind === "contributor_error").map(b => b.source)).toEqual(["bad-shape", "bad-blocker"]);
+        expect(result.blockers.some(b => b.kind === "ok")).toBe(true);
+    });
+    it("bounds the number of blockers", () => {
+        const bus = createEventBus();
+        bus.on(RELEASE_READINESS_EVENT, raw => raw.contribute("many", Array.from({ length: 100 }, (_, i) => blocker("many", "async_run", { id: `r${i}` }))));
+        const result = data(new RpcReleaseBridge(bus, scope).request(command));
+        expect(result.blockers).toHaveLength(65);
+        expect(result.blockers.at(-1)).toMatchObject({ kind: "contributor_error", detail: expect.stringContaining("36 further") });
+    });
+    it("ignores requests for another session and late asynchronous contributions", async () => {
+        const bus = createEventBus();
+        contributor(bus, "subagents", "some-other-session", () => [blocker("subagents", "async_run")]);
+        let late;
+        bus.on(RELEASE_READINESS_EVENT, raw => { late = raw; });
+        const bridge = new RpcReleaseBridge(bus, scope);
+        const result = data(bridge.request(command));
+        expect(result).toMatchObject({ safe: true, blockers: [], contributors: [] });
+        late.contribute("late", [blocker("late", "async_run")]);
+        expect(data(bridge.request(command)).blockers).toEqual([]);
+        expect(late).toMatchObject({ version: 1, sessionId: "host" });
+    });
+    it("rejects malformed commands", () => {
+        const bridge = new RpcReleaseBridge(undefined, scope);
+        expect(bridge.request({ type: "release_readiness", version: 2 })).toMatchObject({ success: false, error: expect.stringContaining("version") });
+        expect(bridge.request({ type: "release_readiness" })).toMatchObject({ success: false });
+        expect(bridge.request({ ...command, id: "x".repeat(129) })).toMatchObject({ success: false });
+        expect(bridge.request({ ...command, id: "a\nb" })).toMatchObject({ success: false });
+        expect(bridge.request({ ...command, method: "spawn" })).toMatchObject({ success: false, error: expect.stringContaining("Malformed") });
+    });
+    it("fails after dispose and does not call contributors", () => {
+        const bus = createEventBus();
+        let calls = 0;
+        contributor(bus, "subagents", "host", () => { calls++; return []; });
+        const bridge = new RpcReleaseBridge(bus, scope);
+        bridge.dispose();
+        expect(bridge.request({ ...command, id: "late" })).toEqual({ id: "late", type: "response", command: "release_readiness", success: false, error: "Release readiness session ended" });
+        expect(calls).toBe(0);
+    });
+});
+describe("RpcReleaseBridge.release (atomic release decision)", () => {
+    const releaseCommand = { type: "release", version: 1 };
+    const result = (reply) => {
+        if (!reply.success || reply.command !== "release")
+            throw new Error(JSON.stringify(reply));
+        return reply.data;
+    };
+    const idleBus = () => {
+        const bus = createEventBus();
+        contributor(bus, "subagents", "host", () => []);
+        contributor(bus, "scheduler", "host", () => []);
+        return bus;
+    };
+    it("commits synchronously, before returning, only when safe and somebody answered", () => {
+        const commits = [];
+        const bridge = new RpcReleaseBridge(idleBus(), scope);
+        const reply = bridge.release({ ...releaseCommand, id: "r1" }, [], readiness => commits.push(readiness));
+        expect(reply).toMatchObject({ id: "r1", type: "response", command: "release", success: true });
+        expect(result(reply)).toEqual({ released: true, readiness: { ...scope, safe: true, blockers: [], contributors: ["subagents", "scheduler"] } });
+        expect(commits).toEqual([result(reply).readiness]);
+    });
+    it("does not commit and returns the blockers when a core or extension blocker exists", () => {
+        let commits = 0;
+        const core = result(new RpcReleaseBridge(idleBus(), scope).release(releaseCommand, [blocker("core", "streaming")], () => { commits++; }));
+        expect(core).toMatchObject({ released: false, readiness: { safe: false, blockers: [{ source: "core", kind: "streaming" }] } });
+        const bus = createEventBus();
+        contributor(bus, "scheduler", "host", () => [blocker("scheduler", "armed_schedule", { id: "s1" })]);
+        const extension = result(new RpcReleaseBridge(bus, scope).release(releaseCommand, [], () => { commits++; }));
+        expect(extension).toMatchObject({ released: false, readiness: { safe: false, contributors: ["scheduler"], blockers: [{ kind: "armed_schedule", id: "s1" }] } });
+        expect(commits).toBe(0);
+    });
+    it("treats nobody answering (no contributors) as not releasable even though readiness is safe", () => {
+        let commits = 0;
+        const none = result(new RpcReleaseBridge(undefined, scope).release(releaseCommand, [], () => { commits++; }));
+        expect(none).toEqual({ released: false, readiness: { ...scope, safe: true, blockers: [], contributors: [] } });
+        // Another session's contributor does not count as an answer either.
+        const foreign = createEventBus();
+        contributor(foreign, "subagents", "another-session", () => []);
+        expect(result(new RpcReleaseBridge(foreign, scope).release(releaseCommand, [], () => { commits++; })).released).toBe(false);
+        expect(commits).toBe(0);
+    });
+    it("fails closed on a throwing contributor", () => {
+        const bus = createEventBus();
+        contributor(bus, "subagents", "host", () => { throw new Error("status.json is corrupt"); });
+        let commits = 0;
+        expect(result(new RpcReleaseBridge(bus, scope).release(releaseCommand, [], () => { commits++; }))).toMatchObject({ released: false, readiness: { blockers: [{ kind: "contributor_error" }] } });
+        expect(commits).toBe(0);
+    });
+    it("validates exactly like release_readiness and never commits an invalid command", () => {
+        const bridge = new RpcReleaseBridge(idleBus(), scope);
+        let commits = 0;
+        const commit = () => { commits++; };
+        expect(bridge.release({ type: "release", version: 2 }, [], commit)).toEqual({ id: undefined, type: "response", command: "release", success: false, error: "Unsupported release version; expected 1" });
+        expect(bridge.release({ type: "release" }, [], commit)).toMatchObject({ success: false });
+        expect(bridge.release({ ...releaseCommand, id: "x".repeat(129) }, [], commit)).toMatchObject({ success: false });
+        expect(bridge.release({ ...releaseCommand, id: "a\nb" }, [], commit)).toMatchObject({ success: false });
+        expect(bridge.release({ ...releaseCommand, method: "spawn" }, [], commit)).toMatchObject({ success: false, error: "Malformed release command" });
+        expect(commits).toBe(0);
+        expect(validateReleaseCommand(releaseCommand)).toBeUndefined();
+        expect(validateReleaseCommand(command)).toBeUndefined();
+        expect(validateReleaseCommand({ type: "release", version: 1, extra: true })).toBe("Malformed release command");
+    });
+    it("fails after dispose without calling contributors or committing", () => {
+        const bridge = new RpcReleaseBridge(idleBus(), scope);
+        bridge.dispose();
+        let commits = 0;
+        expect(bridge.release({ ...releaseCommand, id: "late" }, [], () => { commits++; })).toEqual({ id: "late", type: "response", command: "release", success: false, error: "Release readiness session ended" });
+        expect(commits).toBe(0);
+    });
+    it("decideRelease requires a clean answer from at least one contributor", () => {
+        expect(decideRelease({ safe: true, blockers: [], contributors: ["subagents"] })).toBe(true);
+        expect(decideRelease({ safe: true, blockers: [], contributors: [] })).toBe(false);
+        expect(decideRelease({ safe: false, blockers: [blocker("core", "streaming")], contributors: ["subagents"] })).toBe(false);
+        expect(decideRelease({ safe: true, blockers: [blocker("core", "streaming")], contributors: ["subagents"] })).toBe(false);
+    });
+});
+describe("answerReleaseReadiness / isReleaseBlocker", () => {
+    it("requires a bound session, a valid request and a matching session id", () => {
+        const seen = [];
+        const request = (sessionId) => ({ version: 1, sessionId, contribute: name => { seen.push(name); } });
+        answerReleaseReadiness(request("a"), "x", "a", () => []);
+        answerReleaseReadiness(request("a"), "x", "b", () => []);
+        answerReleaseReadiness(request("a"), "x", null, () => []);
+        answerReleaseReadiness(undefined, "x", "a", () => []);
+        answerReleaseReadiness({ version: 2, sessionId: "a", contribute: () => seen.push("v2") }, "x", "a", () => []);
+        expect(seen).toEqual(["x"]);
+    });
+    it("validates blocker shape and bounds", () => {
+        expect(isReleaseBlocker({ source: "core", kind: "streaming", detail: "d" })).toBe(true);
+        expect(isReleaseBlocker({ source: "core", kind: "streaming", detail: "d", id: "i", since: 1 })).toBe(true);
+        expect(isReleaseBlocker({ source: "core", kind: "streaming", detail: "" })).toBe(false);
+        expect(isReleaseBlocker({ source: "core", kind: "streaming", detail: "d", extra: 1 })).toBe(false);
+        expect(isReleaseBlocker({ source: "core", kind: "streaming", detail: "x".repeat(513) })).toBe(false);
+        expect(isReleaseBlocker({ source: "core", kind: "streaming", detail: "d", since: -1 })).toBe(false);
+        expect(isReleaseBlocker({ source: "core", kind: "streaming", detail: "d", since: 1.5 })).toBe(false);
+        expect(isReleaseBlocker(null)).toBe(false);
+    });
+});
+describe("RpcReleaseBridge.stopAll (stop_all_background kill switch)", () => {
+    const stopCommand = { type: "stop_all_background", version: 1 };
+    const item = (source, kind, extra = {}) => ({ source, kind, detail: `${kind} stopped`, ok: true, ...extra });
+    const result = (reply) => {
+        if (!reply.success || reply.command !== "stop_all_background")
+            throw new Error(JSON.stringify(reply));
+        return reply.data;
+    };
+    const idleCore = () => [];
+    const noBlockers = () => [];
+    /** Registers a stop handler that follows the documented gate (same helper the extensions use). */
+    const stopper = (bus, name, boundSessionId, compute) => bus.on(STOP_ALL_BACKGROUND_EVENT, raw => answerStopAllBackground(raw, name, boundSessionId, compute));
+    it("answers with an empty stopped list and the post-stop readiness on an idle session", async () => {
+        const bus = createEventBus();
+        contributor(bus, "subagents", "host", () => []);
+        stopper(bus, "subagents", "host", () => []);
+        const reply = await new RpcReleaseBridge(bus, scope).stopAll({ ...stopCommand, id: "k1" }, idleCore, noBlockers);
+        expect(reply).toMatchObject({ id: "k1", type: "response", command: "stop_all_background", success: true });
+        expect(result(reply)).toEqual({ ...scope, stopped: [], remaining: { ...scope, safe: true, blockers: [], contributors: ["subagents"] } });
+    });
+    it("runs the core stop and every contributor, in order, and reports remaining AFTER the stop", async () => {
+        const bus = createEventBus();
+        let running = true; // flips when the stop handler runs; the readiness contributor reflects it
+        contributor(bus, "subagents", "host", () => running ? [blocker("subagents", "async_run", { id: "run-1" })] : []);
+        stopper(bus, "scheduler", "host", () => [item("scheduler", "schedule", { id: "s1" })]);
+        stopper(bus, "subagents", "host", () => { running = false; return [item("subagents", "async_run", { id: "run-1" })]; });
+        const events = [];
+        const reply = await new RpcReleaseBridge(bus, scope).stopAll(stopCommand, () => { events.push("core"); return [item("core", "turn")]; }, () => { events.push("remaining"); return []; });
+        const data = result(reply);
+        expect(data.stopped.map(i => `${i.source}:${i.kind}`)).toEqual(["core:turn", "scheduler:schedule", "subagents:async_run"]);
+        expect(data.stopped.every(i => i.ok)).toBe(true);
+        expect(data.remaining).toMatchObject({ safe: true, blockers: [] });
+        expect(events).toEqual(["core", "remaining"]);
+        // Idempotent: nothing left to stop the second time.
+        const again = result(await new RpcReleaseBridge(bus, scope).stopAll(stopCommand, idleCore, noBlockers));
+        expect(again.remaining.safe).toBe(true);
+    });
+    it("isolates failures: a throwing, rejecting or malformed contributor becomes ok:false and the others still run", async () => {
+        const bus = createEventBus();
+        const ran = [];
+        stopper(bus, "boom", "host", () => { throw new Error("status.json is corrupt"); });
+        stopper(bus, "rejects", "host", async () => { throw new Error("runner vanished"); });
+        bus.on(STOP_ALL_BACKGROUND_EVENT, raw => {
+            const request = raw;
+            request.contribute("bad-shape", "nope");
+            request.contribute("bad-item", [{ source: "x", kind: "", detail: "", ok: true }, item("bad-item", "fine")]);
+        });
+        stopper(bus, "healthy", "host", () => { ran.push("healthy"); return [item("healthy", "async_run", { id: "run-9" })]; });
+        const data = result(await new RpcReleaseBridge(bus, scope).stopAll(stopCommand, () => { throw new Error("abort exploded"); }, noBlockers));
+        expect(ran).toEqual(["healthy"]);
+        expect(data.stopped).toEqual([
+            { source: "core", kind: "contributor", detail: "Stop failed: abort exploded", ok: false, error: "abort exploded" },
+            { source: "boom", kind: "contributor", detail: "Stop failed: status.json is corrupt", ok: false, error: "status.json is corrupt" },
+            { source: "rejects", kind: "contributor", detail: "Stop failed: runner vanished", ok: false, error: "runner vanished" },
+            { source: "bad-shape", kind: "contributor", detail: "Malformed stop contribution", ok: false, error: "malformed" },
+            { source: "bad-item", kind: "contributor", detail: "Malformed stop item", ok: false, error: "malformed" },
+            { source: "bad-item", kind: "fine", detail: "fine stopped", ok: true },
+            { source: "healthy", kind: "async_run", id: "run-9", detail: "async_run stopped", ok: true },
+        ]);
+    });
+    it("bounds the total wait: a contributor that never settles is reported ok:false error timeout, the rest are kept", async () => {
+        const bus = createEventBus();
+        stopper(bus, "fast", "host", () => [item("fast", "async_run")]);
+        stopper(bus, "stuck", "host", () => new Promise(() => undefined));
+        const startedAt = Date.now();
+        const data = result(await new RpcReleaseBridge(bus, scope).stopAll(stopCommand, () => new Promise(() => undefined), noBlockers, 60));
+        expect(Date.now() - startedAt).toBeLessThan(2000);
+        expect(data.stopped.map(i => [i.source, i.ok, i.error])).toEqual([["core", false, "timeout"], ["fast", true, undefined], ["stuck", false, "timeout"]]);
+    });
+    it("hands each contributor the shared deadline so it can bound its own waiting", async () => {
+        const bus = createEventBus();
+        let seen = 0;
+        stopper(bus, "waiter", "host", ({ deadline }) => { seen = deadline; return []; });
+        const before = Date.now();
+        await new RpcReleaseBridge(bus, scope).stopAll(stopCommand, idleCore, noBlockers, 1234);
+        expect(seen).toBeGreaterThanOrEqual(before + 1234);
+        expect(seen).toBeLessThanOrEqual(Date.now() + 1234);
+    });
+    it("ignores other sessions' handlers and late contributions, and bounds the item count", async () => {
+        const bus = createEventBus();
+        stopper(bus, "other", "another-session", () => [item("other", "async_run")]);
+        let late;
+        bus.on(STOP_ALL_BACKGROUND_EVENT, raw => { late = raw; });
+        stopper(bus, "many", "host", () => Array.from({ length: 200 }, (_, i) => item("many", "async_run", { id: `r${i}` })));
+        const bridge = new RpcReleaseBridge(bus, scope);
+        const data = result(await bridge.stopAll(stopCommand, idleCore, noBlockers));
+        expect(data.stopped).toHaveLength(129);
+        expect(data.stopped.at(-1)).toMatchObject({ ok: false, error: "truncated", detail: expect.stringContaining("72 further") });
+        expect(data.stopped.some(i => i.source === "other")).toBe(false);
+        late.contribute("late", [item("late", "async_run")]);
+        expect(result(await bridge.stopAll(stopCommand, idleCore, noBlockers)).stopped.some(i => i.source === "late")).toBe(false);
+    });
+    it("fails closed when the bus emit throws", async () => {
+        const throwing = { emit() { throw new Error("bus down"); }, on: () => () => undefined };
+        const data = result(await new RpcReleaseBridge(throwing, scope).stopAll(stopCommand, idleCore, noBlockers));
+        expect(data.stopped).toEqual([{ source: "unknown", kind: "contributor", detail: "Stop failed: bus down", ok: false, error: "bus down" }]);
+    });
+    it("rejects malformed requests with success:false and never calls the core stop or contributors", async () => {
+        const bus = createEventBus();
+        let calls = 0;
+        stopper(bus, "subagents", "host", () => { calls++; return []; });
+        const bridge = new RpcReleaseBridge(bus, scope);
+        const core = () => { calls++; return []; };
+        expect(await bridge.stopAll({ type: "stop_all_background", version: 2 }, core, noBlockers)).toEqual({ id: undefined, type: "response", command: "stop_all_background", success: false, error: "Unsupported stop_all_background version; expected 1" });
+        expect(await bridge.stopAll({ type: "stop_all_background" }, core, noBlockers)).toMatchObject({ success: false });
+        expect(await bridge.stopAll({ ...stopCommand, id: "x".repeat(129) }, core, noBlockers)).toMatchObject({ success: false });
+        expect(await bridge.stopAll({ ...stopCommand, id: "a\nb" }, core, noBlockers)).toMatchObject({ success: false });
+        expect(await bridge.stopAll({ ...stopCommand, method: "spawn" }, core, noBlockers)).toMatchObject({ success: false, error: "Malformed stop_all_background command" });
+        expect(calls).toBe(0);
+        expect(validateReleaseCommand(stopCommand)).toBeUndefined();
+    });
+    it("fails after dispose without calling anything", async () => {
+        const bus = createEventBus();
+        let calls = 0;
+        stopper(bus, "subagents", "host", () => { calls++; return []; });
+        const bridge = new RpcReleaseBridge(bus, scope);
+        bridge.dispose();
+        expect(await bridge.stopAll({ ...stopCommand, id: "late" }, () => { calls++; return []; }, noBlockers)).toEqual({ id: "late", type: "response", command: "stop_all_background", success: false, error: "Release readiness session ended" });
+        expect(calls).toBe(0);
+    });
+    it("validates stop item shape and bounds, and the handler gate", () => {
+        expect(isStopAllBackgroundItem({ source: "core", kind: "turn", detail: "d", ok: true })).toBe(true);
+        expect(isStopAllBackgroundItem({ source: "core", kind: "turn", detail: "d", ok: false, error: "timeout", id: "i" })).toBe(true);
+        expect(isStopAllBackgroundItem({ source: "core", kind: "turn", detail: "d" })).toBe(false);
+        expect(isStopAllBackgroundItem({ source: "core", kind: "turn", detail: "d", ok: "yes" })).toBe(false);
+        expect(isStopAllBackgroundItem({ source: "core", kind: "turn", detail: "d", ok: true, extra: 1 })).toBe(false);
+        expect(isStopAllBackgroundItem({ source: "core", kind: "turn", detail: "x".repeat(513), ok: true })).toBe(false);
+        expect(isStopAllBackgroundItem(null)).toBe(false);
+        const seen = [];
+        const request = (sessionId) => ({ version: 1, sessionId, deadline: Date.now(), contribute: name => { seen.push(name); } });
+        answerStopAllBackground(request("a"), "x", "a", () => []);
+        answerStopAllBackground(request("a"), "x", "b", () => []);
+        answerStopAllBackground(request("a"), "x", null, () => []);
+        answerStopAllBackground(undefined, "x", "a", () => []);
+        answerStopAllBackground({ version: 2, sessionId: "a", contribute: () => seen.push("v2") }, "x", "a", () => []);
+        expect(seen).toEqual(["x"]);
+    });
+});

package/dist/modes/rpc/rpc-client.d.ts

@@ -1,18 +1,15 @@
-/**
- * RPC Client for programmatic access to the coding agent.
- *
- * Spawns the agent in RPC mode and provides a typed API for all operations.
- */
+import type { SubagentRpcSnapshot } from "../../core/subagent-rpc.ts";
+import type { ReleaseReadiness, ReleaseResult, StopAllBackgroundResult } from "../../core/release-rpc.ts";
 import type { AgentMessage, ThinkingLevel } from "@earendil-works/pi-agent-core";
 import type { ImageContent, Model } from "@earendil-works/pi-ai";
-import type { AgentSessionEvent, SessionStats } from "../../core/agent-session.ts";
+import type { SessionStats } from "../../core/agent-session.ts";
 import type { KeybindingsConfig } from "../../core/keybindings.ts";
 import type { Settings } from "../../core/settings-manager.ts";
 import type { BashResult } from "../../core/bash-executor.ts";
 import type { CompactionResult } from "../../core/compaction/index.ts";
 import type { SessionEntry, SessionTreeNode } from "../../core/session-manager.ts";
 import type { ChangelogEntry } from "../../utils/changelog.ts";
-import type { RpcSessionInfo, RpcSessionState, RpcSkillInfo, RpcSlashCommand } from "./rpc-types.ts";
+import type { RpcEvent, IntercomRpcDataMap, IntercomRpcMessageOptions, RpcSessionInfo, RpcSessionState, RpcSkillInfo, RpcSlashCommand } from "./rpc-types.ts";
 export interface RpcClientOptions {
     /** Path to the CLI entry point (default: searches for dist/cli.js) */
     cliPath?: string;
@@ -33,7 +30,7 @@ export interface ModelInfo {
     contextWindow: number;
     reasoning: boolean;
 }
-export type RpcEventListener = (event: AgentSessionEvent) => void;
+export type RpcEventListener = (event: RpcEvent) => void;
 export declare class RpcClient {
     private process;
     private stopReadingStdout;
@@ -97,6 +94,33 @@ export declare class RpcClient {
     /**
      * Get current session state.
      */
+    /** Read-only native subagent snapshot; never invokes a model. */
+    subagentStatus(): Promise<SubagentRpcSnapshot>;
+    /** Authoritative "is it safe to stop this process now" answer; never invokes a model. */
+    releaseReadiness(): Promise<ReleaseReadiness>;
+    /**
+     * Atomic "release if safe". `released: true` means the process has committed to a gentle exit (code 0, no abort) and rejects
+     * every further command except `release`/`release_readiness`; `released: false` carries the blockers and the process keeps running.
+     * "Nobody answered" (no extension contributors) is never released.
+     */
+    release(): Promise<ReleaseResult>;
+    /**
+     * DESTRUCTIVE kill switch for an explicit user "Quit anyway": aborts the turn (retry, compaction, bash, queued messages), stops every
+     * async/detached subagent run of this session (detached runners terminate on their own), disarms this session's session-only
+     * schedules (paused, project schedules untouched) and cancels pending outbound intercom asks. Per-item failures are `ok:false`
+     * in `stopped`; `remaining` is the readiness computed after the stop. Idempotent; refused while the session is releasing.
+     */
+    stopAllBackground(): Promise<StopAllBackgroundResult>;
+    intercomStatus(): Promise<IntercomRpcDataMap["intercom_status"]>;
+    intercomList(): Promise<IntercomRpcDataMap["intercom_list"]>;
+    intercomPending(): Promise<IntercomRpcDataMap["intercom_pending"]>;
+    intercomSend(to: string, options: IntercomRpcMessageOptions): Promise<IntercomRpcDataMap["intercom_send"]>;
+    intercomAsk(to: string, options: IntercomRpcMessageOptions & {
+        timeoutMs?: number;
+    }): Promise<IntercomRpcDataMap["intercom_ask"]>;
+    intercomReply(options: IntercomRpcMessageOptions & {
+        to?: string;
+    }): Promise<IntercomRpcDataMap["intercom_reply"]>;
     getState(): Promise<RpcSessionState>;
     /**
      * Set model by provider and ID.
@@ -425,11 +449,11 @@ export declare class RpcClient {
     /**
      * Collect events until agent becomes idle.
      */
-    collectEvents(timeout?: number): Promise<AgentSessionEvent[]>;
+    collectEvents(timeout?: number): Promise<RpcEvent[]>;
     /**
      * Send prompt and wait for completion, returning all events.
      */
-    promptAndWait(message: string, images?: ImageContent[], timeout?: number): Promise<AgentSessionEvent[]>;
+    promptAndWait(message: string, images?: ImageContent[], timeout?: number): Promise<RpcEvent[]>;
     private handleLine;
     private createProcessExitError;
     private rejectPendingRequests;