@zackbart/connecta 0.34.1 → 0.36.0

package/dist/executors/quickjs.js

@@ -20,7 +20,9 @@ import { msg } from "../errors.js";
 import { InvocationFailure } from "../invocation.js";
 import { brandExecutor } from "../executor-contract.js";
 import { MAX_EXECUTE_LOG_CHARS } from "../executor-result.js";
-import { detach, fromSignal, runEdge } from "../runtime/run.js";
+import { admit } from "../runtime/admission.js";
+import { awaitExecutorLease, executorProgram, provideExecutorProgram } from "../runtime/executor.js";
+import { detach, forkOwned, fromSignal, runEdge } from "../runtime/run.js";
 import { hostCallLabel, MAX_QUICKJS_IPC_BYTES, MAX_QUICKJS_RESULT_BYTES, QUICKJS_RESULT_CHUNK_CHARS, MAX_QUICKJS_HOST_RPC_BYTES, serializedBytes, stringifyBounded, } from "./quickjs-protocol.js";
 export { normalizeCode } from "./quickjs-runtime.js";
 const DEFAULT_TIMEOUT_MS = 30_000;
@@ -114,6 +116,7 @@ function terminate(child) {
         ]);
     });
 }
+let providePoolProgram;
 class QuickJsChildPool {
     /** What `/health` and `connecta doctor` call this sandbox (#368). */
     name = "QuickJS";
@@ -147,66 +150,87 @@ class QuickJsChildPool {
         }));
         this.available = [...this.slots];
     }
-    async acquire(options = {}) {
-        const admission = await this.admission.acquire(options);
-        const slot = this.available.shift();
-        if (!slot) {
-            admission.release();
-            throw new Error("Executor admission invariant failed: no child slot.");
-        }
-        let released = false;
-        let executed = false;
-        return {
-            waitMs: admission.waitMs,
-            execute: async (code, providers) => {
+    acquire(options = {}) {
+        return runEdge(this.acquireProgram(options));
+    }
+    acquireProgram(options = {}) {
+        return Effect.gen({ self: this }, function* () {
+            const admission = yield* admit(this.admission, options);
+            const slot = this.available.shift();
+            if (!slot) {
+                admission.release();
+                return yield* Effect.fail(new Error("Executor admission invariant failed: no child slot."));
+            }
+            let released = false;
+            let executed = false;
+            const logs = [];
+            const stopped = Deferred.makeUnsafe();
+            const execute = (code, providers) => Effect.suspend(() => {
                 if (released)
-                    throw new Error("Executor lease was already released.");
+                    return Effect.fail(new Error("Executor lease was already released."));
                 if (executed)
-                    throw new Error("Executor lease may execute only once.");
+                    return Effect.fail(new Error("Executor lease may execute only once."));
                 executed = true;
-                return runEdge(this.run(slot, code, providers, options.signal));
-            },
-            release: () => {
-                if (released)
-                    return;
-                released = true;
-                // A lease let go mid-run takes its child with it: the program is
-                // abandoned, and the next lease must not inherit its leftovers.
-                if (slot.active) {
-                    this.rejectActive(slot, new Error("Executor lease was released during execution."));
-                    this.recycle(slot);
-                }
-                this.available.push(slot);
-                admission.release();
-            },
-        };
+                return Effect.raceFirst(this.run(slot, code, providers, options.signal, logs), Deferred.await(stopped));
+            });
+            const lease = {
+                waitMs: admission.waitMs,
+                execute: (code, providers) => runEdge(execute(code, providers)),
+                release: () => {
+                    if (released)
+                        return;
+                    released = true;
+                    // Revoke ownership before a successor can see the slot. A release
+                    // during readiness/backoff also interrupts the old run, even though
+                    // slot.active does not exist yet; the warm child may keep starting.
+                    if (slot.active) {
+                        this.rejectActive(slot, new Error("Executor lease was released during execution."));
+                        this.recycle(slot);
+                    }
+                    Deferred.doneUnsafe(stopped, Exit.fail(new Error("Executor lease was released during execution.")));
+                    this.available.push(slot);
+                    admission.release();
+                },
+            };
+            provideExecutorProgram(lease, execute, () => logs);
+            return lease;
+        });
     }
     admissionSnapshot() {
         return this.admission.snapshot();
     }
-    async execute(code, providers) {
-        const lease = await this.acquire();
-        try {
-            return await lease.execute(code, providers);
-        }
-        finally {
-            lease.release();
-        }
+    execute(code, providers) {
+        return runEdge(this.executeProgram(code, providers));
     }
-    async close() {
-        if (this.closed)
-            return;
-        this.closed = true;
-        this.admission.close();
-        for (const slot of this.slots)
-            this.stopSlot(slot);
-        await Promise.allSettled(this.retiring);
+    executeProgram(code, providers) {
+        return Effect.scoped(Effect.gen({ self: this }, function* () {
+            const lease = yield* Effect.acquireRelease(Effect.suspend(() => this.acquire !== QuickJsChildPool.prototype.acquire ||
+                this.admission.activeCount >= this.admission.concurrency
+                ? awaitExecutorLease((signal) => this.acquire({ signal }))
+                : this.acquireProgram()), (lease) => Effect.sync(() => lease.release()), { interruptible: true });
+            return yield* executorProgram(lease, code, providers);
+        }));
+    }
+    close() {
+        return runEdge(Effect.gen({ self: this }, function* () {
+            if (this.closed)
+                return;
+            this.closed = true;
+            this.admission.close();
+            for (const slot of this.slots)
+                this.stopSlot(slot);
+            yield* Effect.forEach([...this.retiring], (finished) => Deferred.await(finished), { discard: true });
+        }));
+    }
+    static {
+        // Register each instance without publishing native methods or Effect types.
+        providePoolProgram = (pool) => provideExecutorProgram(pool, (code, providers) => pool.executeProgram(code, providers));
     }
     // One execution on a leased slot: a ready child, the run message, then the
     // outcome raced against the wall deadline and the caller's abort. Either of
     // those settles the outcome and recycles the child; the race's losers are
     // interrupted, which clears their timer and abort listener.
-    run(slot, code, providers, signal) {
+    run(slot, code, providers, signal, logs = []) {
         return Effect.gen({ self: this }, function* () {
             if (signal?.aborted) {
                 return yield* Effect.fail(cancelled("Execution was cancelled before it started."));
@@ -242,12 +266,13 @@ class QuickJsChildPool {
             child.channel?.ref();
             const active = {
                 id,
-                logs: [],
+                logs,
                 logChars: 0,
                 resultChunks: [],
                 resultBytes: 0,
                 providers: providerMap,
                 outcome: Deferred.makeUnsafe(),
+                hosts: Scope.makeUnsafe(),
             };
             slot.active = active;
             try {
@@ -288,7 +313,12 @@ class QuickJsChildPool {
             if (signal) {
                 contenders.push(fromSignal(signal).pipe(Effect.catch(() => endWith(cancelled("Execution was cancelled.")))));
             }
-            return yield* Effect.raceAllFirst(contenders);
+            return yield* Effect.raceAllFirst(contenders).pipe(Effect.onInterrupt(() => Effect.sync(() => {
+                if (slot.active !== active)
+                    return;
+                this.rejectActive(slot, new Error("Executor execution was interrupted."));
+                this.recycle(slot);
+            })));
         });
     }
     // A ready child on the slot: the warm one, or a new one once any crash
@@ -341,7 +371,7 @@ class QuickJsChildPool {
                     "@zackbart/connecta/quickjs) when bundling the server."));
             }
             const scope = Scope.makeUnsafe();
-            return Effect.acquireRelease(Effect.sync(() => this.forkChild(slot, scope, childPath, sourceMode)).pipe(Effect.tap((child) => Effect.forkIn(this.startupWatchdog(slot, child), scope))), terminate).pipe(Scope.provide(scope));
+            return Effect.acquireRelease(Effect.sync(() => this.forkChild(slot, scope, childPath, sourceMode)).pipe(Effect.tap((child) => forkOwned(this.startupWatchdog(slot, child), scope))), terminate).pipe(Scope.provide(scope));
         });
     }
     // Fails a child that never reports ready. It lives in the child's Scope,
@@ -375,7 +405,7 @@ class QuickJsChildPool {
         subprocess.stderr?.unref?.();
         slot.child = child;
         subprocess.on("message", (message) => {
-            void this.onMessage(slot, child, message);
+            this.onMessage(slot, child, message);
         });
         subprocess.on("error", (error) => {
             if (slot.child !== child)
@@ -411,7 +441,7 @@ class QuickJsChildPool {
         subprocess.channel?.unref();
         return child;
     }
-    async onMessage(slot, child, message) {
+    onMessage(slot, child, message) {
         // A compromised child is exactly the adversary this process boundary
         // contains, and this handler's rejection would crash the serving process.
         // Refuse malformed intake before touching any field.
@@ -455,7 +485,7 @@ class QuickJsChildPool {
         if (message.type === "host-call") {
             if (message.jobId !== active.id)
                 return;
-            await this.handleHostCall(slot, child.process, active, message);
+            void detach(forkOwned(this.handleHostCall(slot, child.process, active, message), active.hosts));
             return;
         }
         if ((message.type !== "result" && message.type !== "result-chunk") || message.jobId !== active.id)
@@ -499,66 +529,78 @@ class QuickJsChildPool {
             this.recycle(slot);
         }
     }
-    async handleHostCall(slot, child, active, message) {
-        let payloadJson;
-        try {
-            if (serializedBytes(message.payloadJson) > MAX_QUICKJS_HOST_RPC_BYTES) {
-                // Refused before parsing, so there is no address to name here: parsing
-                // an over-limit payload to improve its error message would spend the
-                // work the limit exists to refuse.
-                throw new RangeError("Host call arguments exceeded the IPC limit.");
+    handleHostCall(slot, child, active, message) {
+        return Effect.gen({ self: this }, function* () {
+            let payloadJson;
+            try {
+                if (serializedBytes(message.payloadJson) > MAX_QUICKJS_HOST_RPC_BYTES) {
+                    // Refused before parsing, so there is no address to name here: parsing
+                    // an over-limit payload to improve its error message would spend the
+                    // work the limit exists to refuse.
+                    throw new RangeError("Host call arguments exceeded the IPC limit.");
+                }
+                const payload = JSON.parse(message.payloadJson);
+                const provider = active.providers.get(payload.namespace);
+                const fn = provider && Object.hasOwn(provider.fns, payload.functionName)
+                    ? provider.fns[payload.functionName]
+                    : undefined;
+                if (!fn) {
+                    throw new Error(`Unknown function ${payload.namespace}.${payload.functionName}`);
+                }
+                // The provider is an ordinary Promise leaf. Its host fiber belongs to
+                // this run and is interrupted when the child settles or is recycled.
+                const result = yield* Effect.result(Effect.tryPromise({ try: () => Promise.resolve(fn(...payload.args)), catch: (error) => error }));
+                if (result._tag === "Failure") {
+                    payloadJson = errorPayload(result.failure);
+                }
+                else {
+                    const value = result.success;
+                    try {
+                        payloadJson = stringifyBounded({ ok: true, value }, `Host result from ${hostCallLabel(payload)}`, MAX_QUICKJS_HOST_RPC_BYTES);
+                    }
+                    catch (err) {
+                        // The guest reads this text, so it names the address the program called
+                        // rather than only the generic connecta.call bridge function.
+                        const label = hostCallLabel(payload);
+                        const detail = err instanceof RangeError
+                            ? `Host result from ${label} exceeds the ${MAX_QUICKJS_HOST_RPC_BYTES}-byte serialized bridge limit.`
+                            : `Host result from ${label} could not be serialized: ${msg(err)}`;
+                        payloadJson = errorPayload(detail);
+                    }
+                }
+            }
+            catch (err) {
+                payloadJson = errorPayload(err);
+            }
+            if (!child.connected || slot.active !== active)
+                return;
+            const response = {
+                type: "host-result",
+                jobId: message.jobId,
+                callId: message.callId,
+                payloadJson,
+            };
+            try {
+                stringifyBounded(response, "QuickJS host-result IPC envelope");
             }
-            const payload = JSON.parse(message.payloadJson);
-            const provider = active.providers.get(payload.namespace);
-            const fn = provider && Object.hasOwn(provider.fns, payload.functionName) ? provider.fns[payload.functionName] : undefined;
-            if (!fn) {
-                throw new Error(`Unknown function ${payload.namespace}.${payload.functionName}`);
+            catch {
+                // L6/X10: settle the rejected call even if the outer encoding overflows.
+                response.payloadJson = errorPayload(`QuickJS host-result IPC envelope could not be serialized within the ${MAX_QUICKJS_IPC_BYTES}-byte IPC limit.`);
             }
-            const value = await fn(...payload.args);
+            const failedSend = (error) => {
+                if (!error || slot.active !== active)
+                    return;
+                this.rejectActive(slot, error);
+                this.recycle(slot);
+            };
             try {
-                payloadJson = stringifyBounded({ ok: true, value }, `Host result from ${hostCallLabel(payload)}`, MAX_QUICKJS_HOST_RPC_BYTES);
+                stringifyBounded(response, "QuickJS host-result IPC envelope");
+                child.send(response, failedSend);
             }
             catch (err) {
-                // The guest reads this text, so it names the address the program called
-                // rather than only the generic connecta.call bridge function.
-                const label = hostCallLabel(payload);
-                const detail = err instanceof RangeError
-                    ? `Host result from ${label} exceeds the ${MAX_QUICKJS_HOST_RPC_BYTES}-byte serialized bridge limit.`
-                    : `Host result from ${label} could not be serialized: ${msg(err)}`;
-                payloadJson = errorPayload(detail);
+                failedSend(err instanceof Error ? err : new Error(msg(err)));
             }
-        }
-        catch (err) {
-            payloadJson = errorPayload(err);
-        }
-        if (!child.connected || slot.active !== active)
-            return;
-        const response = {
-            type: "host-result",
-            jobId: message.jobId,
-            callId: message.callId,
-            payloadJson,
-        };
-        try {
-            stringifyBounded(response, "QuickJS host-result IPC envelope");
-        }
-        catch {
-            // L6/X10: settle the rejected call even if the outer encoding overflows.
-            response.payloadJson = errorPayload(`QuickJS host-result IPC envelope could not be serialized within the ${MAX_QUICKJS_IPC_BYTES}-byte IPC limit.`);
-        }
-        const failedSend = (error) => {
-            if (!error || slot.active !== active)
-                return;
-            this.rejectActive(slot, error);
-            this.recycle(slot);
-        };
-        try {
-            stringifyBounded(response, "QuickJS host-result IPC envelope");
-            child.send(response, failedSend);
-        }
-        catch (err) {
-            failedSend(err instanceof Error ? err : new Error(msg(err)));
-        }
+        }).pipe(Effect.catchDefect(() => Effect.void));
     }
     resolveActive(slot, outcome) {
         const active = slot.active;
@@ -580,7 +622,11 @@ class QuickJsChildPool {
         Deferred.doneUnsafe(active.outcome, Exit.fail(error));
     }
     clearActive(slot) {
+        const active = slot.active;
         slot.active = undefined;
+        active?.providers.clear();
+        if (active)
+            void detach(Scope.close(active.hosts, Exit.void));
         slot.child?.process.unref();
         slot.child?.process.channel?.unref();
     }
@@ -617,9 +663,12 @@ class QuickJsChildPool {
             slot.child = undefined;
         if (!child.retired) {
             child.retired = true;
-            const closing = detach(Scope.close(child.scope, Exit.void));
-            this.retiring.add(closing);
-            void closing.then(() => this.retiring.delete(closing));
+            const finished = Deferred.makeUnsafe();
+            this.retiring.add(finished);
+            void detach(Scope.close(child.scope, Exit.void).pipe(Effect.ensuring(Effect.sync(() => {
+                this.retiring.delete(finished);
+                Deferred.doneUnsafe(finished, Exit.void);
+            }))));
         }
         if (readyError)
             Deferred.doneUnsafe(child.ready, Exit.fail(readyError));
@@ -631,5 +680,7 @@ class QuickJsChildPool {
  * double-acquire deadlock at concurrency 1.
  */
 export function quickJsExecutor(options = {}) {
-    return brandExecutor(new QuickJsChildPool(options), "leased");
+    const pool = new QuickJsChildPool(options);
+    providePoolProgram(pool);
+    return brandExecutor(pool, "leased");
 }

package/dist/guarded-transport.js

@@ -0,0 +1,50 @@
+// The plain runtime slot keeps the HTTP kit and Node sender off the root
+// and Worker graphs. /node installs its sender when listen() starts serving.
+import { ConnectorCallError } from "./errors.js";
+let owned;
+/** Runtime configuration, never request data. Returns the previous slot for isolated fixtures. */
+export function configureGuardedTransport(transport) {
+    const previous = owned;
+    owned = transport;
+    return previous;
+}
+export function guardedTransport(write) {
+    if (owned)
+        return owned;
+    const node = typeof globalThis.WebSocketPair === "undefined" &&
+        typeof process !== "undefined" &&
+        process.versions?.node !== undefined;
+    if (node && write) {
+        throw new ConnectorCallError("connector_call_failed", "Guarded writes on Node require the owned transport: serve with listen from @zackbart/connecta/node.", { retryable: false });
+    }
+    // workerd supplies its native network implementation, with manual redirects.
+    // Node reads can use native fetch without claiming a single physical attempt.
+    return { send: (url, init) => globalThis.fetch(url, init) };
+}
+/** Legacy/fake senders dispatch immediately; the owned sender may first establish a tunnel. */
+export function sendGuarded(transport, url, init, beforeDispatch) {
+    if (transport.delaysDispatch)
+        return transport.send(url, init, beforeDispatch);
+    beforeDispatch();
+    return transport.send(url, init);
+}
+/** SDK-authenticated token/registration/revocation POST, with no physical replay or redirect. */
+export async function sendCredentialPost(input, init, beforeDispatch = () => { }) {
+    const transport = guardedTransport(true);
+    try {
+        if ((init.method ?? "GET").toUpperCase() !== "POST")
+            throw new Error("Expected credential POST.");
+        return await sendGuarded(transport, new URL(input), { ...init, redirect: "manual" }, beforeDispatch);
+    }
+    catch (error) {
+        if (init.signal?.aborted)
+            throw init.signal.reason;
+        if (error instanceof ConnectorCallError)
+            throw error;
+        // SDKs may log transport errors. No native exception/cause can quote a form,
+        // client secret, grant, request header or credential-bearing endpoint here.
+        throw new ConnectorCallError("connector_call_failed", "OAuth credential request did not return a confirmed response.", {
+            retryable: false,
+        });
+    }
+}

package/dist/guest-runtime.js

@@ -224,7 +224,7 @@ export function programError(raw, code) {
         /(?:const|let|var|function|\()\s*connecta\b/.test(code)) {
         hint = "Do not shadow connecta. Use the host-provided connecta global.";
     }
-    else if (/callTool|mixpanel|\bskills\b|connecta\.(?:guide|skills)/.test(message) ||
+    else if (/callTool|\bskills\b|connecta\.(?:guide|skills)/.test(message) ||
         (["TypeError", "ReferenceError"].includes(name) && /connecta\.(?:guide|skills)\b/.test(code))) {
         hint =
             "Use connecta.call(address, args), connecta.search, connecta.describe, connecta.result, and connecta.skill(name). Services are addressed by connector.tool, never guest globals.";