@promigence/sdk 0.1.0-beta.12 → 0.1.0-beta.13

package/dist/core.d.ts

@@ -1,5 +1,5 @@
 /** Promigence SDK — constants, error hierarchy and shared types. */
-export declare const VERSION = "0.1.0-beta.12";
+export declare const VERSION = "0.1.0-beta.13";
 export declare const DOCS_URL = "https://promigence.ai";
 /** The error reference; each code is an anchor on it (the API's `docs` link has the same form). */
 export declare const ERRORS_DOCS_URL = "https://www.promigence.ai/docs/errors";

package/dist/core.js

@@ -1,5 +1,5 @@
 import { hintArg } from "./hint.js";
-export const VERSION = "0.1.0-beta.12";
+export const VERSION = "0.1.0-beta.13";
 export const DOCS_URL = "https://promigence.ai";
 export const ERRORS_DOCS_URL = "https://www.promigence.ai/docs/errors";
 export const DEFAULT_API_URL = "https://api.promigence.ai/v1";

package/dist/dispatcher.d.ts

@@ -48,6 +48,8 @@ interface Timeouts {
 export declare function longRequestDispatcher(timeoutMs: number, base?: object | undefined): object | undefined;
 /** Test and diagnostics view. Not part of the public API. */
 export declare const __dispatcherInternals: {
+    /** How many times `longRequestDispatcher` has been asked (each request on the `fetch` path asks once). */
+    lookups(): number;
     /** The timeouts a dispatcher of ours sets, or `undefined` for any other value. */
     timeoutsOf(d: unknown): Timeouts | undefined;
     /** The process's global dispatcher composed with exactly these timeouts (never cached). */

package/dist/dispatcher.js

@@ -47,7 +47,9 @@ function composeWith(base, ms) {
     timeouts.set(d, { headersTimeout: ms, bodyTimeout: ms });
     return d;
 }
+let lookups = 0;
 export function longRequestDispatcher(timeoutMs, base = firstGlobalDispatcher()) {
+    lookups++;
     try {
         const needed = timeoutMs + LONG_REQUEST_SLACK_MS;
         if (!(needed > FETCH_DEFAULT_TIMEOUT_MS))
@@ -73,6 +75,9 @@ export function longRequestDispatcher(timeoutMs, base = firstGlobalDispatcher())
     }
 }
 export const __dispatcherInternals = {
+    lookups() {
+        return lookups;
+    },
     timeoutsOf(d) {
         return d !== null && typeof d === "object" ? timeouts.get(d) : undefined;
     },

package/dist/http2.d.ts

@@ -69,6 +69,8 @@ export interface Http2Init {
     signal?: AbortSignal;
     /** Read by `fetch` on fallback only. */
     dispatcher?: object;
+    /** Worked out on fallback only, when no `dispatcher` was given: the one `fetch` should carry for `timeoutMs`. */
+    dispatcherFor?: (timeoutMs: number) => object | undefined;
     /** Phase stamps when `PROMIGENCE_SDK_TRACE=1`. */
     trace?: TraceStamp;
 }
@@ -142,9 +144,13 @@ export declare class Http2Transport {
      */
     fetch(url: string, init: Http2Init, replayable: boolean): Promise<Response | H2Response>;
 }
+/** The one `Http2Transport` for every client whose fallback is `fallback` (it keeps nothing of a client's). */
+export declare function sharedTransport(fallback: FetchLike): Http2Transport;
 export declare function warmTransport(): void;
 /** Test and diagnostics view of the process-wide pools. Not part of the public API. */
 export declare const __http2Internals: {
+    /** How many request URLs have been read (each new URL once; the same URL again is not read again). */
+    targetReads(): number;
     pools(): Array<{
         origin: string;
         sessions: number;
@@ -181,6 +187,8 @@ export declare const __http2Internals: {
         answered: number;
         everReady: boolean;
         closedReason: string;
+        messages: number;
+        posts: number;
     } | undefined;
     /** The transport thread's number of connections and spacing between new requests on one, for an environment (`threadKnobs`). */
     threadKnobs(env: NodeJS.ProcessEnv): {
@@ -188,6 +196,8 @@ export declare const __http2Internals: {
         gapUs: number;
         pace: string;
     };
+    /** Tests: make the transport thread stop answering (it reads nothing more), as a stuck one would. */
+    wedgeThreadForTest(): void;
     /** Tests: make the transport thread fail as a crash would. */
     crashThreadForTest(): void;
     /** The early lookup, for tests: start one with a platform, DNS servers and hosts file of the test's own. */

package/dist/http2.js

@@ -845,18 +845,18 @@ const earlies = new Map();
 const MAX_EARLIES = 4;
 const EARLY_MAX_AGE_MS = 60_000;
 const EARLY_TIMEOUT_MS = 2_000;
-const LOOKUP_AT_LOAD = (() => {
+const DNS_AT_LOAD = (() => {
     try {
-        return nodeDns()?.lookup;
+        return nodeDns();
     }
     catch {
         return undefined;
     }
 })();
+const LOOKUP_AT_LOAD = DNS_AT_LOAD?.lookup;
 function lookupReplaced() {
     try {
-        const d = nodeDns();
-        return d !== undefined && d.lookup !== LOOKUP_AT_LOAD;
+        return DNS_AT_LOAD !== undefined && DNS_AT_LOAD.lookup !== LOOKUP_AT_LOAD;
     }
     catch {
         return true;
@@ -1290,12 +1290,13 @@ function targetOf(url, known, remember) {
 }
 function fetchInit(init, deadline) {
     const timeout = AbortSignal.timeout(Math.max(0, Math.ceil(deadline - performance.now())));
+    const dispatcher = init.dispatcher ?? init.dispatcherFor?.(init.timeoutMs);
     return {
         method: init.method,
         headers: init.headers,
         signal: init.signal === undefined ? timeout : AbortSignal.any([timeout, init.signal]),
         ...(init.body === undefined ? {} : { body: init.body }),
-        ...(init.dispatcher === undefined ? {} : { dispatcher: init.dispatcher }),
+        ...(dispatcher === undefined ? {} : { dispatcher }),
     };
 }
 function fetchFailed(cause) {
@@ -1312,11 +1313,14 @@ class HandBack {
 const UNSENT = new HandBack(0, 0);
 const VIA_FETCH = Symbol("via-fetch");
 const THREAD_GRACE_MS = 1_000;
+const THREAD_SWEEP_MS = 250;
+const THREAD_MARKS = 4096;
 const THREAD_PHASES = ["w.got", "w.sent", "w.head", "w.end"];
 class TransportThread {
     origin;
     worker;
     port;
+    acks;
     state = "starting";
     sessions = 0;
     limit = DEFAULT_STREAM_LIMIT;
@@ -1326,13 +1330,26 @@ class TransportThread {
     inflight = new Map();
     nextId = 1;
     listening = false;
+    refd = false;
+    sweep;
+    freeMarks = [];
+    messages = 0;
+    outbox = [];
+    turnOpen = false;
+    posts = 0;
     answered = 0;
     pace = THREAD_DEFAULTS.pace;
     hrOffset = Number(process.hrtime.bigint()) / 1e6 - performance.now();
-    constructor(origin, worker, port) {
+    constructor(origin, worker, port, acks) {
         this.origin = origin;
         this.worker = worker;
         this.port = port;
+        this.acks = acks;
+        for (let i = acks.length - 1; i >= 0; i--)
+            this.freeMarks.push(i);
+    }
+    acked(p) {
+        return Atomics.load(this.acks, p.mark) === p.id;
     }
     poll() {
         for (;;) {
@@ -1349,12 +1366,13 @@ class TransportThread {
         }
     }
     ready() {
-        if (this.state !== "closed")
+        if (!this.listening && this.state !== "closed")
             this.poll();
-        return this.state === "ready" && this.sessions > 0 && this.inflight.size < this.sessions * this.limit;
+        return this.state === "ready" && this.sessions > 0 && this.inflight.size < this.sessions * this.limit && this.freeMarks.length > 0;
     }
     onMessage(m) {
         const msg = m;
+        this.messages++;
         switch (msg?.t) {
             case "ready":
                 if (this.state === "starting" || this.state === "ready") {
@@ -1391,12 +1409,6 @@ class TransportThread {
             case "closed":
                 this.close(msg.reason ?? "closed");
                 return;
-            case "ack": {
-                const p = this.inflight.get(msg.id ?? -1);
-                if (p !== undefined)
-                    p.acked = true;
-                return;
-            }
             case "res":
             case "err":
                 this.settle(m);
@@ -1480,10 +1492,12 @@ class TransportThread {
         if (this.closedReason === "")
             this.closedReason = reason;
         traceEvent("thread:closed");
+        this.outbox = [];
         for (const [id, p] of [...this.inflight]) {
+            const sent = this.acked(p);
             this.inflight.delete(id);
             this.release(p);
-            if (!p.acked)
+            if (!sent)
                 p.resolve(UNSENT);
             else if (p.replayable)
                 p.resolve(new HandBack(0, 1));
@@ -1505,18 +1519,49 @@ class TransportThread {
             this.poll();
             this.port.on("message", (m) => { this.onMessage(m); });
         }
+        if (this.refd)
+            return;
+        this.refd = true;
         safely(() => { this.port.ref(); });
         safely(() => { this.worker.ref(); });
+        this.sweep = setInterval(() => { this.sweepBackstops(); }, THREAD_SWEEP_MS);
+        safely(() => { this.sweep?.unref?.(); });
     }
     unref() {
+        if (this.sweep !== undefined) {
+            clearInterval(this.sweep);
+            this.sweep = undefined;
+        }
+        if (!this.refd)
+            return;
+        this.refd = false;
         safely(() => { this.port.unref(); });
         safely(() => { this.worker.unref(); });
     }
+    sweepBackstops() {
+        this.poll();
+        const now = performance.now();
+        let late = false;
+        for (const [id, p] of [...this.inflight]) {
+            if (p.backstopAt > now)
+                continue;
+            late = true;
+            this.inflight.delete(id);
+            this.release(p);
+            try {
+                this.port.postMessage({ t: "cancel", id });
+            }
+            catch { }
+            p.reject(timeoutReason());
+        }
+        if (late)
+            this.close("no answer from the transport thread");
+    }
     release(p) {
         if (p.signal !== undefined && p.onAbort !== undefined)
             p.signal.removeEventListener("abort", p.onAbort);
-        if (p.backstop !== undefined)
-            clearTimeout(p.backstop);
+        Atomics.store(this.acks, p.mark, 0);
+        this.freeMarks.push(p.mark);
         if (this.inflight.size === 0)
             this.unref();
     }
@@ -1541,8 +1586,11 @@ class TransportThread {
             headers["content-length"] = Buffer.byteLength(init.body, "utf8");
         const id = this.nextId++;
         const tr = init.trace;
+        const place = this.freeMarks.pop();
+        if (place === undefined)
+            return Promise.resolve(UNSENT);
         return new Promise((resolve, reject) => {
-            const p = { resolve, reject, method: init.method, replayable, acked: false, trace: tr };
+            const p = { id, resolve, reject, method: init.method, replayable, mark: place, backstopAt: performance.now() + remaining + THREAD_GRACE_MS, trace: tr };
             const signal = init.signal;
             if (signal !== undefined) {
                 p.signal = signal;
@@ -1551,47 +1599,59 @@ class TransportThread {
                         return;
                     this.inflight.delete(id);
                     this.release(p);
-                    try {
-                        this.port.postMessage({ t: "cancel", id });
+                    const queued = this.outbox.findIndex((b) => b.id === id);
+                    if (queued >= 0)
+                        this.outbox.splice(queued, 1);
+                    else {
+                        try {
+                            this.port.postMessage({ t: "cancel", id });
+                        }
+                        catch { }
                     }
-                    catch { }
                     reject(signal.reason);
                 };
                 signal.addEventListener("abort", p.onAbort, { once: true });
             }
-            p.backstop = setTimeout(() => {
-                this.poll();
-                if (!this.inflight.has(id))
-                    return;
-                this.inflight.delete(id);
-                this.release(p);
-                try {
-                    this.port.postMessage({ t: "cancel", id });
-                }
-                catch { }
-                reject(timeoutReason());
-                this.close("no answer from the transport thread");
-            }, remaining + THREAD_GRACE_MS);
-            safely(() => { p.backstop?.unref?.(); });
             this.inflight.set(id, p);
             this.ref();
-            try {
-                const paced = this.pace === "all" || (this.pace === "creates" && init.method === "POST" && CREATE_PATH.test(target.path));
-                this.port.postMessage({ t: "req", id, headers, sensitive: ["authorization"], body: init.body, timeoutMs: remaining, replayable, paced });
+            const paced = this.pace === "all" || (this.pace === "creates" && init.method === "POST" && CREATE_PATH.test(target.path));
+            this.outbox.push({ id, msg: { t: "req", id, mark: place, headers, sensitive: ["authorization"], body: init.body, timeoutMs: remaining, replayable, paced }, p, resolve, trace: tr });
+            if (!this.turnOpen) {
+                this.turnOpen = true;
+                queueMicrotask(() => { this.turnOpen = false; this.handOver(); });
+                this.handOver();
             }
-            catch {
-                this.inflight.delete(id);
-                this.release(p);
-                resolve(UNSENT);
-                return;
+            else if (this.outbox.length >= OUTBOX_GROUP)
+                this.handOver();
+        });
+    }
+    handOver() {
+        if (this.outbox.length === 0)
+            return;
+        const batch = this.outbox;
+        this.outbox = [];
+        try {
+            this.port.postMessage(batch.length === 1 ? batch[0].msg : { t: "reqs", list: batch.map((b) => b.msg) });
+            this.posts++;
+        }
+        catch {
+            for (const b of batch) {
+                if (!this.inflight.has(b.id))
+                    continue;
+                this.inflight.delete(b.id);
+                this.release(b.p);
+                b.resolve(UNSENT);
             }
-            if (tr !== undefined) {
-                mark(tr, "sub");
-                tr.via = "thread";
+            return;
+        }
+        for (const b of batch)
+            if (b.trace !== undefined) {
+                mark(b.trace, "sub");
+                b.trace.via = "thread";
             }
-        });
     }
 }
+const OUTBOX_GROUP = 8;
 let transportThread;
 function threadFor(origin) {
     const t = transportThread;
@@ -1636,9 +1696,10 @@ function startTransportThread(origin, onFail) {
         const knobs = threadKnobs();
         const file = typeof seam.transportFile === "string" ? seam.transportFile : here.replace(/http2\.js$/, "transport-worker.js");
         const { port1, port2 } = new MessageChannel();
+        const acks = new Int32Array(new SharedArrayBuffer(4 * THREAD_MARKS));
         const worker = new Worker(file.startsWith("file:") ? new URL(file) : file, {
             workerData: {
-                promigenceTransport: true, port: port2, origin: origin.origin, sessions: knobs.sessions, gapUs: knobs.gapUs,
+                promigenceTransport: true, port: port2, acks, origin: origin.origin, sessions: knobs.sessions, gapUs: knobs.gapUs,
                 firstUseMs: tuning.loadFirstUseMs, idleMs: IDLE_CLOSE_MS, connectTimeoutMs: CONNECT_TIMEOUT_MS,
                 lookupTimeoutMs: EARLY_TIMEOUT_MS, trace: TRACE_ON,
                 servers: tuning.earlyServers ?? (Array.isArray(seam.servers) ? seam.servers : undefined),
@@ -1651,7 +1712,7 @@ function startTransportThread(origin, onFail) {
         });
         worker.unref();
         port1.unref();
-        const t = new TransportThread(origin.origin, worker, port1);
+        const t = new TransportThread(origin.origin, worker, port1, acks);
         t.pace = knobs.pace;
         t.onFail = onFail;
         worker.on("error", () => { t.poll(); t.close("error"); });
@@ -1673,6 +1734,18 @@ function knownPrefix(url) {
     }
     return undefined;
 }
+let lastTargetUrl;
+let lastTargetRead;
+let targetReads = 0;
+function lastTarget(url) {
+    if (url === lastTargetUrl)
+        return lastTargetRead;
+    targetReads++;
+    const target = targetOf(url, knownPrefix(url), remember);
+    lastTargetUrl = url;
+    lastTargetRead = target;
+    return target;
+}
 function remember(p) {
     for (let i = 0; i < prefixes.length; i++)
         if (prefixes[i].text === p.text)
@@ -1708,7 +1781,7 @@ export class Http2Transport {
         const deadline = performance.now() + init.timeoutMs;
         let target;
         try {
-            target = targetOf(url, knownPrefix(url), remember);
+            target = lastTarget(url);
         }
         catch {
             return this.viaFetch(url, init, deadline);
@@ -1768,6 +1841,15 @@ export class Http2Transport {
         }
     }
 }
+let sharedFallback;
+let shared;
+export function sharedTransport(fallback) {
+    if (shared === undefined || sharedFallback !== fallback) {
+        shared = new Http2Transport(fallback);
+        sharedFallback = fallback;
+    }
+    return shared;
+}
 export function warmTransport() {
     const res = toResponse(200, { "content-type": "application/json" }, Buffer.from("{}"), "POST");
     res.header("server-timing");
@@ -1780,6 +1862,9 @@ export function warmTransport() {
     exchange({ end() { } }, undefined, { origin: none, host: none, path: none }, undefined, 0).catch(() => { });
 }
 export const __http2Internals = {
+    targetReads() {
+        return targetReads;
+    },
     pools() {
         return [...pools.values()].map((p) => ({
             origin: p.origin.origin,
@@ -1820,11 +1905,17 @@ export const __http2Internals = {
         if (t === undefined)
             return undefined;
         t.poll();
-        return { state: t.state, sessions: t.sessions, limit: t.limit, answered: t.answered, everReady: t.everReady, closedReason: t.closedReason };
+        return { state: t.state, sessions: t.sessions, limit: t.limit, answered: t.answered, everReady: t.everReady, closedReason: t.closedReason, messages: t.messages, posts: t.posts };
     },
     threadKnobs(env) {
         return threadKnobs(env);
     },
+    wedgeThreadForTest() {
+        try {
+            transportThread?.port.postMessage({ t: "wedge-for-test" });
+        }
+        catch { }
+    },
     crashThreadForTest() {
         try {
             transportThread?.port.postMessage({ t: "crash-for-test" });

package/dist/keyed.d.ts

@@ -0,0 +1,6 @@
+/**
+ * Is `method path` a create that takes an `Idempotency-Key`? `path` is relative to `/v1` and may
+ * carry a query string. The list is the API reference's (generated from the operations that
+ * document the header), so a create the API keys is never sent unkeyed by this client.
+ */
+export declare function isKeyedCreate(method: string, path: string): boolean;

package/dist/keyed.js

@@ -0,0 +1,55 @@
+import { KEYED_CREATES } from "./keyed.gen.js";
+const KEYED_PATTERNS = KEYED_CREATES.map(([m, p]) => [m, p.split("/").filter(Boolean)]);
+const KEYED_METHODS = new Set(KEYED_CREATES.map(([m]) => m));
+let keyedLastMethod = "";
+let keyedLastPath = "";
+let keyedLastAnswer = false;
+let keyedReads = 0;
+export function isKeyedCreate(method, path) {
+    if (!KEYED_METHODS.has(method))
+        return false;
+    if (path === keyedLastPath && method === keyedLastMethod)
+        return keyedLastAnswer;
+    const answer = keyedCreateOf(method, path);
+    keyedLastMethod = method;
+    keyedLastPath = path;
+    keyedLastAnswer = answer;
+    return answer;
+}
+function keyedCreateOf(method, path) {
+    keyedReads++;
+    let end = path.indexOf("?");
+    if (end < 0)
+        end = path.length;
+    for (let p = 0; p < KEYED_PATTERNS.length; p++) {
+        const entry = KEYED_PATTERNS[p];
+        if (entry[0] === method && segmentsMatch(path, end, entry[1]))
+            return true;
+    }
+    return false;
+}
+function segmentsMatch(path, end, pat) {
+    let i = 0;
+    let k = 0;
+    for (;;) {
+        while (i < end && path.charCodeAt(i) === 0x2f)
+            i++;
+        if (i >= end)
+            return k === pat.length;
+        if (k >= pat.length)
+            return false;
+        let j = i;
+        while (j < end && path.charCodeAt(j) !== 0x2f)
+            j++;
+        const s = pat[k];
+        if (s.charCodeAt(0) !== 0x7b && (j - i !== s.length || !path.startsWith(s, i)))
+            return false;
+        k++;
+        i = j;
+    }
+}
+export const __keyedInternals = {
+    reads() {
+        return keyedReads;
+    },
+};

package/dist/proxy.js

@@ -57,12 +57,23 @@ export function noProxy(host, port, env = process.env) {
     }
     return false;
 }
+let proxyLastInputs;
+let proxyLast;
 export function proxyFor(url, env = process.env) {
     const https = envOf(env, "HTTPS_PROXY");
     const http = envOf(env, "HTTP_PROXY");
     const all = envOf(env, "ALL_PROXY");
     if (https === undefined && http === undefined && all === undefined)
         return undefined;
+    const inputs = `${url}\n${https ?? "\0"}\n${http ?? "\0"}\n${all ?? "\0"}\n${envOf(env, "NO_PROXY") ?? "\0"}`;
+    if (inputs === proxyLastInputs)
+        return proxyLast;
+    const found = proxyForOf(url, env, https, http, all);
+    proxyLastInputs = inputs;
+    proxyLast = found;
+    return found;
+}
+function proxyForOf(url, env, https, http, all) {
     let u;
     try {
         u = new URL(url);

package/dist/sandbox.d.ts

@@ -396,7 +396,9 @@ export declare class Sandbox {
     }>;
     /**
      * `forkHandles`, plus what `create` needs to end a run it was interrupted starting: the key the
-     * create is sent under, a signal for it and its waits, and the start options as sent.
+     * create is sent under, a signal for it and its waits, and the start options as sent (`onStart`
+     * is handed the very options sent, the signal included); `client` and `count` stand in for the
+     * options' own.
      */
     private static forkHandlesWith;
     /** Attach to a running sandbox (`GET /sandboxes/:id`). */

package/dist/sandbox.js

@@ -168,16 +168,19 @@ function onSigint() {
         return;
     void Promise.allSettled(cleanups.map((f) => f())).finally(() => { process.kill(process.pid, "SIGINT"); });
 }
+function createAborted() {
+    return new TimeoutError("Sandbox.create was aborted by the caller's signal; anything it had started was ended", "Nothing to fix: the caller aborted it.");
+}
 function holdSigint(cleanup) {
     if (typeof process === "undefined" || typeof process.listenerCount !== "function")
-        return () => { };
-    if (process.listenerCount("SIGINT") - (sigintHeld ? 1 : 0) > 0)
-        return () => { };
-    creatingNow.add(cleanup);
+        return undefined;
     if (!sigintHeld) {
+        if (process.listenerCount("SIGINT") > 0)
+            return undefined;
         process.once("SIGINT", onSigint);
         sigintHeld = true;
     }
+    creatingNow.add(cleanup);
     return () => {
         creatingNow.delete(cleanup);
         if (creatingNow.size === 0 && sigintHeld) {
@@ -455,7 +458,7 @@ export class Sandbox {
             ...(opts.apiKey === undefined ? {} : { apiKey: opts.apiKey }),
             ...(opts.apiUrl === undefined ? {} : { apiUrl: opts.apiUrl }),
         });
-        const aborted = () => new TimeoutError("Sandbox.create was aborted by the caller's signal; anything it had started was ended", "Nothing to fix: the caller aborted it.");
+        const aborted = createAborted;
         if (opts.signal?.aborted)
             throw aborted();
         if (opts.image !== undefined) {
@@ -476,24 +479,31 @@ export class Sandbox {
         else if (snapshotIdOrAlias === undefined || snapshotIdOrAlias === "base") {
             snapshotIdOrAlias = DEFAULT_SNAPSHOT;
         }
-        const stop = new AbortController();
         const key = newIdempotencyKey();
         let sent;
         let runId;
         let ending;
         const end = () => (ending ??= endInterruptedCreate(client, runId, sent));
-        const release = holdSigint(() => { stop.abort(); return end(); });
-        const onAbort = () => { stop.abort(); };
-        opts.signal?.addEventListener("abort", onAbort, { once: true });
+        let stop;
+        const release = holdSigint(() => { stop?.abort(); return end(); });
+        const callerSignal = opts.signal;
+        const onAbort = callerSignal === undefined ? undefined : () => { stop?.abort(); };
+        if (release !== undefined || callerSignal !== undefined)
+            stop = new AbortController();
+        if (onAbort !== undefined)
+            callerSignal.addEventListener("abort", onAbort, { once: true });
         try {
             let handles;
             try {
-                ({ runId, handles } = await Sandbox.forkHandlesWith(snapshotIdOrAlias, { ...opts, count: 1, client }, {
-                    idempotencyKey: key, signal: stop.signal, onStart: (s) => { sent = s; },
-                }));
+                const extra = {
+                    idempotencyKey: key, onStart: (s) => { sent = s; }, client, count: 1,
+                };
+                if (stop !== undefined)
+                    extra.signal = stop.signal;
+                ({ runId, handles } = await Sandbox.forkHandlesWith(snapshotIdOrAlias, opts, extra));
             }
             catch (e) {
-                if (stop.signal.aborted) {
+                if (stop?.signal.aborted) {
                     await end();
                     throw aborted();
                 }
@@ -506,7 +516,7 @@ export class Sandbox {
                 return await first;
             }
             catch (e) {
-                if (stop.signal.aborted) {
+                if (stop?.signal.aborted) {
                     await end();
                     throw aborted();
                 }
@@ -518,8 +528,9 @@ export class Sandbox {
             }
         }
         finally {
-            release();
-            opts.signal?.removeEventListener("abort", onAbort);
+            release?.();
+            if (onAbort !== undefined)
+                callerSignal.removeEventListener("abort", onAbort);
         }
     }
     static async fork(snapshotIdOrAlias, opts = {}) {
@@ -530,11 +541,11 @@ export class Sandbox {
         return Sandbox.forkHandlesWith(snapshotIdOrAlias, opts, {});
     }
     static async forkHandlesWith(snapshotIdOrAlias, opts, extra) {
-        const client = opts.client ?? new PromigenceClient({
+        const client = extra.client ?? opts.client ?? new PromigenceClient({
             ...(opts.apiKey === undefined ? {} : { apiKey: opts.apiKey }),
             ...(opts.apiUrl === undefined ? {} : { apiUrl: opts.apiUrl }),
         });
-        const count = opts.count ?? 1;
+        const count = extra.count ?? opts.count ?? 1;
         const spendCap = spendCapFromEnv(opts.spendCap);
         const start = { snapshot: snapshotIdOrAlias, count };
         if (spendCap !== undefined)
@@ -555,8 +566,10 @@ export class Sandbox {
             start.optimizeFor = opts.optimizeFor;
         if (extra.idempotencyKey !== undefined)
             start.idempotencyKey = extra.idempotencyKey;
-        extra.onStart?.({ ...start });
-        const run = await client.runs.start(extra.signal === undefined ? start : { ...start, signal: extra.signal });
+        if (extra.signal !== undefined)
+            start.signal = extra.signal;
+        extra.onStart?.(start);
+        const run = await client.runs.start(start);
         const envs = opts.envs;
         const mk = (ref) => {
             const init = { sandboxId: ref.sandbox_id, runId: run.run_id, snapshot: snapshotIdOrAlias, client };