Skip to content

A self-improving RLM agent for coding workflows and long-running autonomous tasks.

Rust

bound subagent kernel-boot concurrency (#294)

kta556dfde8274
diff --git a/packages/coding-agent/src/core/agent-session.ts b/packages/coding-agent/src/core/agent-session.ts
index 0bcdc7c2a5..e2f79877bb 100644
--- a/packages/coding-agent/src/core/agent-session.ts
+++ b/packages/coding-agent/src/core/agent-session.ts
@@ -4081,6 +4081,9 @@ export class AgentSession {
if (!(await ensureTool("rg", true))) {
throw new Error(MISSING_RIPGREP_MESSAGE);
}
+ if (isRlmChildRunCancelled(run)) {
+ throw new Error(run.error ?? "RLM child cancelled");
+ }
childRuntime = await this._createRlmSubagentRuntime(subagentOptions);
const child = childRuntime.session;
childSession = child;
diff --git a/packages/coding-agent/src/core/kernel/boot-gate.ts b/packages/coding-agent/src/core/kernel/boot-gate.ts
new file mode 100644
index 0000000000..5813d5b755
--- /dev/null
+++ b/packages/coding-agent/src/core/kernel/boot-gate.ts
@@ -0,0 +1,27 @@
+import { cpus } from "node:os";
+import { Semaphore } from "../../utils/semaphore.js";
+
+// Above core count because boots are IO-bound (cold imports), but capped so a
+// fan-out can't thrash the FS past the port-resolve window.
+const DEFAULT_KERNEL_BOOT_CONCURRENCY = Math.min(16, Math.max(4, (cpus().length || 4) * 2));
+const MAX_KERNEL_BOOT_CONCURRENCY = 64;
+
+export function resolveKernelBootConcurrency(): number {
+ const raw = process.env.PRIME_AGENT_MAX_CONCURRENT_KERNEL_BOOTS;
+ if (raw === undefined || !/^\d+$/.test(raw)) {
+ return DEFAULT_KERNEL_BOOT_CONCURRENCY;
+ }
+ const parsed = Number.parseInt(raw, 10);
+ // A malformed or out-of-range value (incl. 0, e.g. "00") falls back to the
+ // default rather than mis-bounding the gate or throwing at module load.
+ if (parsed < 1) {
+ return DEFAULT_KERNEL_BOOT_CONCURRENCY;
+ }
+ return Math.min(MAX_KERNEL_BOOT_CONCURRENCY, parsed);
+}
+
+const kernelBootSemaphore = new Semaphore(resolveKernelBootConcurrency());
+
+export function withKernelBootPermit<T>(boot: () => Promise<T>, signal?: AbortSignal): Promise<T> {
+ return kernelBootSemaphore.run(boot, signal);
+}
diff --git a/packages/coding-agent/src/core/tools/ipython.ts b/packages/coding-agent/src/core/tools/ipython.ts
index 404bfaa15b..c47a30ab22 100644
--- a/packages/coding-agent/src/core/tools/ipython.ts
+++ b/packages/coding-agent/src/core/tools/ipython.ts
@@ -5,6 +5,7 @@ import type { ImageContent, TextContent } from "@earendil-works/pi-ai";
import { type Static, Type } from "typebox";
import { IMAGE_MIME_TYPES } from "../../utils/mime.js";
import type { ToolDefinition } from "../extensions/types.js";
+import { withKernelBootPermit } from "../kernel/boot-gate.js";
import type { KernelBootstrapProgressHandler } from "../kernel/bootstrap.js";
import {
type HostRequestHandlers,
@@ -181,6 +182,7 @@ export class IpythonKernelProvisioner {
private readonly startupListeners = new Set<KernelBootstrapProgressHandler>();
private lastStartupMessage?: string;
private _lastRestore?: RestoreResult;
+ private readonly disposeController = new AbortController();
constructor(
private readonly cwd: string,
@@ -219,6 +221,10 @@ export class IpythonKernelProvisioner {
/** Dispose the kernel owned by this provisioner, including one still starting up. */
async dispose(): Promise<void> {
+ // Drops a still-queued boot out of the semaphore and short-circuits an
+ // in-flight startKernel before it spawns, so a disposed session's boot
+ // doesn't waste a slot during a fan-out.
+ this.disposeController.abort();
const pending = this.managerPromise;
this.managerPromise = undefined;
this.startedManager = undefined;
@@ -295,9 +301,20 @@ export class IpythonKernelProvisioner {
? { path: snapshotPathIn(snapshotDir), manifestPath: manifestPathIn(snapshotDir) }
: undefined,
});
+ // Emitted synchronously (before the permit await) so a listener attaching
+ // mid-flight can replay the current stage.
this.emitStartupProgress("Starting IPython kernel...");
- await m.start({ onBootstrapProgress: (message) => this.emitStartupProgress(message) });
- // Whether a snapshot existed decides if we notify the model on success.
+ // Only the process spawn + port resolve contends for OS resources under a
+ // fan-out, and it is bounded by start()'s own timeouts — so the permit
+ // covers only start(). Restore/bootstrap run per-kernel afterwards and are
+ // unbounded execute()s; holding the global permit across them could pin it
+ // forever on a wedged bootstrap and starve every other session's boot.
+ const signal = this.disposeController.signal;
+ await withKernelBootPermit(() => {
+ // Disposed while queued for the permit — don't spawn a kernel nobody wants.
+ if (signal.aborted) throw new Error("Kernel provisioner disposed before start");
+ return m.start({ onBootstrapProgress: (message) => this.emitStartupProgress(message) });
+ }, signal);
let pendingRestore: RestoreResult | undefined;
try {
// Revive a prior session's namespace before the bootstrap, so the bootstrap
diff --git a/packages/coding-agent/src/utils/semaphore.ts b/packages/coding-agent/src/utils/semaphore.ts
new file mode 100644
index 0000000000..382c9bf531
--- /dev/null
+++ b/packages/coding-agent/src/utils/semaphore.ts
@@ -0,0 +1,63 @@
+/**
+ * Counting semaphore for bounding async concurrency. FIFO: waiters acquire in
+ * the order they queued.
+ */
+export class Semaphore {
+ private available: number;
+ private readonly waiters: Array<() => void> = [];
+
+ constructor(permits: number) {
+ if (!Number.isInteger(permits) || permits < 1) {
+ throw new Error(`Semaphore permits must be a positive integer, got ${permits}`);
+ }
+ this.available = permits;
+ }
+
+ get queueLength(): number {
+ return this.waiters.length;
+ }
+
+ private async acquire(signal?: AbortSignal): Promise<void> {
+ if (signal?.aborted) {
+ throw signal.reason ?? new Error("aborted");
+ }
+ if (this.available > 0) {
+ this.available -= 1;
+ return;
+ }
+ // A queued waiter can be aborted before it gets a permit; on abort it
+ // removes itself from the queue so it never consumes a slot.
+ await new Promise<void>((resolve, reject) => {
+ const waiter = (): void => {
+ signal?.removeEventListener("abort", onAbort);
+ resolve();
+ };
+ const onAbort = (): void => {
+ const i = this.waiters.indexOf(waiter);
+ if (i !== -1) this.waiters.splice(i, 1);
+ reject(signal?.reason ?? new Error("aborted"));
+ };
+ this.waiters.push(waiter);
+ signal?.addEventListener("abort", onAbort, { once: true });
+ });
+ }
+
+ private release(): void {
+ const next = this.waiters.shift();
+ if (next) {
+ next();
+ } else {
+ this.available += 1;
+ }
+ }
+
+ /** Run `fn` while holding a permit, releasing it even if `fn` throws. Rejects without running if `signal` aborts while queued. */
+ async run<T>(fn: () => Promise<T>, signal?: AbortSignal): Promise<T> {
+ await this.acquire(signal);
+ try {
+ return await fn();
+ } finally {
+ this.release();
+ }
+ }
+}
diff --git a/packages/coding-agent/test/boot-gate.test.ts b/packages/coding-agent/test/boot-gate.test.ts
new file mode 100644
index 0000000000..795d3db907
--- /dev/null
+++ b/packages/coding-agent/test/boot-gate.test.ts
@@ -0,0 +1,24 @@
+import { afterEach, describe, expect, it } from "vitest";
+import { resolveKernelBootConcurrency } from "../src/core/kernel/boot-gate.js";
+
+const ENV = "PRIME_AGENT_MAX_CONCURRENT_KERNEL_BOOTS";
+
+describe("resolveKernelBootConcurrency", () => {
+ afterEach(() => {
+ delete process.env[ENV];
+ });
+
+ it("never returns a value below 1 (so the semaphore can't throw at load)", () => {
+ for (const bad of ["0", "00", "000", "abc", "3.9", "-1", "8 junk", ""]) {
+ process.env[ENV] = bad;
+ expect(resolveKernelBootConcurrency()).toBeGreaterThanOrEqual(1);
+ }
+ });
+
+ it("honors a clean positive integer, clamped to the max", () => {
+ process.env[ENV] = "8";
+ expect(resolveKernelBootConcurrency()).toBe(8);
+ process.env[ENV] = "999999";
+ expect(resolveKernelBootConcurrency()).toBe(64);
+ });
+});
diff --git a/packages/coding-agent/test/ipython-provisioner.test.ts b/packages/coding-agent/test/ipython-provisioner.test.ts
index b4a903799e..fa8d684b3b 100644
--- a/packages/coding-agent/test/ipython-provisioner.test.ts
+++ b/packages/coding-agent/test/ipython-provisioner.test.ts
@@ -97,6 +97,21 @@ describe("IpythonKernelProvisioner", () => {
expect(provisioner.manager).toBeUndefined();
});
+ it("dispose() before the boot slot prevents the kernel from spawning", async () => {
+ const { python, countRuns } = writeFakePython();
+ let release: () => void = () => {};
+ const gate = new Promise<void>((r) => {
+ release = r;
+ });
+ const provisioner = new IpythonKernelProvisioner(tempDir, { python, readyGate: gate });
+
+ const started = provisioner.ensure().catch(() => {});
+ const disposed = provisioner.dispose(); // aborts while the boot waits on readyGate
+ release();
+ await Promise.all([started, disposed]);
+ expect(countRuns()).toBe(0); // disposed boot must never spawn a kernel
+ });
+
it("waits for readyGate before starting the kernel", async () => {
const { python, countRuns } = writeFakePython();
let release: () => void = () => {};
diff --git a/packages/coding-agent/test/semaphore.test.ts b/packages/coding-agent/test/semaphore.test.ts
new file mode 100644
index 0000000000..bcef2bc975
--- /dev/null
+++ b/packages/coding-agent/test/semaphore.test.ts
@@ -0,0 +1,106 @@
+/**
+ * Tests for the async Semaphore used to bound subagent kernel-boot concurrency.
+ */
+
+import { describe, expect, it } from "vitest";
+import { Semaphore } from "../src/utils/semaphore.js";
+
+function deferred<T>(): { promise: Promise<T>; resolve: (value: T) => void } {
+ let resolve!: (value: T) => void;
+ const promise = new Promise<T>((r) => {
+ resolve = r;
+ });
+ return { promise, resolve };
+}
+
+describe("Semaphore", () => {
+ it("rejects non-positive permit counts", () => {
+ expect(() => new Semaphore(0)).toThrow();
+ expect(() => new Semaphore(-1)).toThrow();
+ expect(() => new Semaphore(1.5)).toThrow();
+ });
+
+ it("never exceeds the permit count under heavy fan-out", async () => {
+ const limit = 3;
+ const total = 50;
+ const sem = new Semaphore(limit);
+ let active = 0;
+ let peak = 0;
+ let completed = 0;
+
+ await Promise.all(
+ Array.from({ length: total }, () =>
+ sem.run(async () => {
+ active += 1;
+ peak = Math.max(peak, active);
+ await new Promise((r) => setTimeout(r, 1));
+ active -= 1;
+ completed += 1;
+ }),
+ ),
+ );
+
+ expect(peak).toBeLessThanOrEqual(limit);
+ expect(completed).toBe(total);
+ });
+
+ it("releases the permit when the task throws", async () => {
+ const sem = new Semaphore(1);
+ await expect(sem.run(async () => Promise.reject(new Error("boom")))).rejects.toThrow("boom");
+ // If the permit leaked, this second acquire would hang forever.
+ await expect(sem.run(async () => "ok")).resolves.toBe("ok");
+ });
+
+ it("hands permits to waiters in FIFO order", async () => {
+ const sem = new Semaphore(1);
+ const order: number[] = [];
+ const gate = deferred<void>();
+
+ // Holder occupies the single permit until we release `gate`.
+ const holder = sem.run(async () => {
+ await gate.promise;
+ });
+
+ // Queue three waiters; they should run in the order they queued.
+ const waiters = [0, 1, 2].map((i) =>
+ sem.run(async () => {
+ order.push(i);
+ }),
+ );
+
+ expect(sem.queueLength).toBe(3);
+ gate.resolve();
+ await Promise.all([holder, ...waiters]);
+ expect(order).toEqual([0, 1, 2]);
+ });
+
+ it("a queued waiter aborts out of the queue without consuming a permit", async () => {
+ const sem = new Semaphore(1);
+ const gate = deferred<void>();
+ const holder = sem.run(async () => {
+ await gate.promise;
+ });
+
+ const ac = new AbortController();
+ const queued = sem.run(async () => "ran", ac.signal);
+ expect(sem.queueLength).toBe(1);
+
+ ac.abort();
+ await expect(queued).rejects.toBeTruthy();
+ expect(sem.queueLength).toBe(0);
+
+ // The aborted waiter must not have stolen the permit: once the holder
+ // releases, a fresh acquire runs immediately.
+ gate.resolve();
+ await holder;
+ await expect(sem.run(async () => "ok")).resolves.toBe("ok");
+ });
+
+ it("rejects immediately if the signal is already aborted", async () => {
+ const sem = new Semaphore(1);
+ const ac = new AbortController();
+ ac.abort();
+ await expect(sem.run(async () => "ran", ac.signal)).rejects.toBeTruthy();
+ await expect(sem.run(async () => "ok")).resolves.toBe("ok");
+ });
+});