@scriptc/compiler 0.0.12 → 0.0.14

package/dist/frontend/lowering/lower-server.js

@@ -12,7 +12,7 @@ import * as ts from "../ts7/adapter.js";
 import { ladderFenceExpr, nodeThrowExpr } from "./lowerer.js";
 import { isJsSourceFile, locOf } from "../program.js";
 import { arrayOf, BOOL, BYTES_U8, canBoxFuncIntoDyn, canConvertToDyn, DYN, DYN_HANDLE_KINDS, F64, funcOf, HTTP2SESSION_T, HTTP2STREAM_T, HTTPCLIENTREQ_T, HTTPREQ_T, HTTPRES_T, NETSERVER_T, NETSOCKET_T, NULL_T, SECURECTX_T, STRING, UNDEFINED_T, typeKey, VOID } from "../../ir/nodes.js";
-import { builtinFenceHintOf, builtinModuleFnOf, fenceOrDropOptionKey, HTTP_CLIENT_DOCUMENTED_OPTIONS, HTTP_SERVER_DOCUMENTED_OPTIONS, HTTP2_SECURE_SERVER_DOCUMENTED_OPTIONS, HTTPS_CLIENT_DOCUMENTED_OPTIONS, sideEffectFreeOptionValue, TLS_SERVER_DOCUMENTED_OPTIONS, } from "./surfaces.js";
+import { AGENT_DOCUMENTED_OPTIONS, builtinFenceHintOf, builtinModuleFnOf, fenceOrDropOptionKey, HTTP_CLIENT_DOCUMENTED_OPTIONS, HTTP_SERVER_DOCUMENTED_OPTIONS, HTTP2_SECURE_SERVER_DOCUMENTED_OPTIONS, HTTPS_CLIENT_DOCUMENTED_OPTIONS, sideEffectFreeOptionValue, TLS_SERVER_DOCUMENTED_OPTIONS, } from "./surfaces.js";
 import { conditionalSpreadOf } from "./lower-exprs.js";
 /** The lowered value members of the net module — the surfaces.ts table's
  * spoke-side twin (the call SHAPES are all special-cased here, so the
@@ -1244,6 +1244,40 @@ function lowerNetSocketMethodCall(L, call, access) {
         const ms = L.lowerExprExpecting(args[0], F64);
         return { kind: "libCall", fn: "net.sockSetTimeout", args: [receiver, ms], type: VOID, loc };
     }
+    if (name === "pause" || name === "resume") {
+        // Flow control (the struct's flag comments in scr_net.c): pause holds
+        // reads off — kernel/TCP backpressure is the buffer; resume flows
+        // (and discards sans listeners, so 'end' is reachable). Both answer
+        // the socket, Node's chaining.
+        if (args.length !== 0) {
+            L.noLowering(`${name} with ${args.length} arguments`, call, `the form is ${name}()`);
+        }
+        const receiver = handleReceiver(L, access.expression, NETSOCKET_T);
+        const fn = name === "pause" ? "net.sockPause" : "net.sockResume";
+        return { kind: "libCall", fn, args: [receiver], type: NETSOCKET_T, loc };
+    }
+    if (name === "setNoDelay") {
+        // TCP_NODELAY on the live fd; missing/undefined means true (Node).
+        // Answers the socket, Node's chaining.
+        if (args.length > 1) {
+            L.noLowering(`setNoDelay with ${args.length} arguments`, call, "the form is setNoDelay(noDelay?)");
+        }
+        const receiver = handleReceiver(L, access.expression, NETSOCKET_T);
+        const enable = args.length === 1
+            ? L.lowerExprExpecting(args[0], BOOL)
+            : boolLit(true, loc);
+        return { kind: "libCall", fn: "net.sockSetNoDelay", args: [receiver, enable], type: NETSOCKET_T, loc };
+    }
+    if (name === "destroySoon") {
+        // end() now, destroy once the FIN actually flushed — Node's
+        // 'finish'-then-destroy.
+        requireStatementPosition(L, call, "socket.destroySoon()");
+        if (args.length !== 0) {
+            L.noLowering(`destroySoon with ${args.length} arguments`, call, "the form is destroySoon()");
+        }
+        const receiver = handleReceiver(L, access.expression, NETSOCKET_T);
+        return { kind: "libCall", fn: "net.sockDestroySoon", args: [receiver], type: VOID, loc };
+    }
     if (name === "read") {
         // socket.read(n?) — the demux peek. Answers the interned
         // `Buffer | null` union: exactly n buffered bytes, or null (Node's
@@ -1311,6 +1345,12 @@ function lowerNetSocketMethodCall(L, call, access) {
                             : "net.sockOnConnect";
             return { kind: "libCall", fn, args: [receiver, cb, once], type: VOID, loc };
         }
+        if (event === "finish") {
+            // Fires once when the FIN goes out — once either way (the event
+            // happens at most once per socket).
+            const { cb } = lowerCallbackArg(L, args[1], "finish listeners", 0, () => false, "use ()", []);
+            return { kind: "libCall", fn: "net.sockOnFinish", args: [receiver, cb], type: VOID, loc };
+        }
         if (event === "secureConnect") {
             // The TLS client's post-handshake event: on a TLS socket the
             // 'connect' list already fires at establishment (scr_net.c's
@@ -1794,6 +1834,17 @@ export function lowerServerProperty(L, expr) {
         const receiver = handleReceiver(L, expr.expression, NETSOCKET_T);
         return { kind: "libCall", fn: "net.sockWritable", args: [receiver], type: BOOL, loc };
     }
+    if (recvKind === "netSocket" && L.isStdlibMember(expr) && expr.name.text === "bytesWritten") {
+        // Every byte the write paths accepted (buffered included — Node
+        // counts those too; plaintext on TLS sockets).
+        const receiver = handleReceiver(L, expr.expression, NETSOCKET_T);
+        return { kind: "libCall", fn: "net.sockBytesWritten", args: [receiver], type: F64, loc };
+    }
+    if (recvKind === "netSocket" && L.isStdlibMember(expr) && expr.name.text === "readable") {
+        // true until the read half is done (peer FIN / destroy).
+        const receiver = handleReceiver(L, expr.expression, NETSOCKET_T);
+        return { kind: "libCall", fn: "net.sockReadable", args: [receiver], type: BOOL, loc };
+    }
     if (recvKind === "netSocket" && L.isStdlibMember(expr) && expr.name.text === "remoteAddress") {
         // `string | undefined` — Node's read-time caching: a value read while
         // connected survives destroy; never-read sockets answer undefined
@@ -2037,6 +2088,113 @@ function lowerHttpCreateServerForms(L, expr, what, loc) {
  * createServer (Node's Server class IS the factory's product); called
  * from lowerNew ahead of the stdlib-constructor fence. Null when the
  * callee is not the http module's Server. */
+/** `new http.Agent(opts?)` / `new https.Agent(opts?)` (property access or
+ * named import): the Agent lowers to a checked-dynamic HANDLE —
+ * getName/destroy and the sockets/requests/freeSockets counters dispatch
+ * through the dyn handle ops, and the request path threads it (the
+ * requestAgent rows). Options parse at the LITERAL construction site:
+ * keepAlive (a boolean value — TRUE throws the runtime's named pooling
+ * fence: this client dials one connection per request), keepAliveMsecs /
+ * maxSockets / maxFreeSockets / timeout / port as numbers, scheduling
+ * DROPS (no free pool exists, so selection order cannot observe), other
+ * documented keys fence by name, and undocumented keys drop like Node
+ * drops them. Null when the callee isn't the http/https Agent. */
+export function lowerHttpAgentNew(L, expr) {
+    const callee = expr.expression;
+    const bi = ts.isPropertyAccessExpression(callee) && callee.name.text === "Agent"
+        ? L.builtinMemberOf(callee)
+        : ts.isIdentifier(callee)
+            ? L.builtinImportOf(callee)
+            : null;
+    if (!bi || bi.member !== "Agent" || (bi.module !== "http" && bi.module !== "https"))
+        return null;
+    const loc = locOf(expr);
+    const api = `new ${bi.module}.Agent`;
+    const numLit = (value) => ({ kind: "numLit", value, type: F64, loc });
+    const boolAt = (value) => ({ kind: "boolLit", value, type: BOOL, loc });
+    let keepAlive = boolAt(false);
+    let kaMsecs = numLit(-1);
+    let maxSockets = numLit(-1);
+    let maxFree = numLit(-1);
+    let timeout = numLit(-1);
+    let port = numLit(-1);
+    const args = expr.arguments ?? [];
+    if (args.length > 1) {
+        L.noLowering(`${api} with ${args.length} arguments`, expr, "the supported form is new Agent(options?)");
+    }
+    if (args.length === 1) {
+        const optsNode = stripParensAndCasts(args[0]);
+        if (!ts.isObjectLiteralExpression(optsNode)) {
+            L.noLowering(`${api} with a non-literal options value`, args[0], "spell the options as an object literal at the construction site");
+        }
+        for (const prop of optsNode.properties) {
+            if (ts.isSpreadAssignment(prop)) {
+                L.noLowering(`${api} with an options spread`, prop, "write each option inline");
+            }
+            let initializer;
+            if (ts.isPropertyAssignment(prop) &&
+                (ts.isIdentifier(prop.name) || ts.isStringLiteral(prop.name))) {
+                initializer = prop.initializer;
+            }
+            else if (ts.isShorthandPropertyAssignment(prop)) {
+                initializer = null;
+            }
+            else {
+                L.noLowering(`${api} options with computed keys`, prop, "each option must be a plain `name: value` (or shorthand) entry with a literal key");
+            }
+            const key = prop.name.text;
+            const lowerVal = (want) => {
+                const v = initializer !== null
+                    ? L.lowerExpr(initializer)
+                    : L.lowerShorthandValue(prop);
+                if (v.type.kind === "dyn") {
+                    return { kind: "dynCheck", value: v, type: want === "bool" ? BOOL : F64, loc: locOf(prop) };
+                }
+                if (v.type.kind !== want) {
+                    L.noLowering(`a ${api} '${key}' option of '${L.fmt(v.type)}' values`, prop, want === "bool" ? "the option value must be a boolean" : "the option value must be a number");
+                }
+                return v;
+            };
+            switch (key) {
+                case "keepAlive":
+                    keepAlive = lowerVal("bool");
+                    break;
+                case "keepAliveMsecs":
+                    kaMsecs = lowerVal("f64");
+                    break;
+                case "maxSockets":
+                    maxSockets = lowerVal("f64");
+                    break;
+                case "maxFreeSockets":
+                    maxFree = lowerVal("f64");
+                    break;
+                case "timeout":
+                    timeout = lowerVal("f64");
+                    break;
+                case "port":
+                    // Node merges agent options under portless request options —
+                    // the settable defaultPort carries this one.
+                    port = lowerVal("f64");
+                    break;
+                case "scheduling":
+                    // Free-socket selection order: no free pool exists here (no
+                    // keep-alive reuse), so the choice cannot observe — dropped.
+                    if (initializer !== null)
+                        L.lowerExpr(initializer); // evaluate, like Node
+                    break;
+                default:
+                    fenceOrDropOptionKey(L, prop, key, api, AGENT_DOCUMENTED_OPTIONS, "keepAlive, keepAliveMsecs, maxSockets, maxFreeSockets, timeout, port, and scheduling are the supported options");
+            }
+        }
+    }
+    return {
+        kind: "libCall",
+        fn: "http.agentNew",
+        args: [boolAt(bi.module === "https"), keepAlive, kaMsecs, maxSockets, maxFree, timeout, port],
+        type: DYN,
+        loc,
+    };
+}
 export function lowerHttpServerNew(L, expr) {
     const callee = expr.expression;
     const isHttpServer = (ts.isPropertyAccessExpression(callee) &&
@@ -2341,9 +2499,45 @@ function lowerTlsModuleCall(L, expr, bi, loc) {
         }
         return { kind: "libCall", fn: "tls.createSecureContext", args: [opts.cert, opts.key], type: SECURECTX_T, loc };
     }
+    // The CA-store introspection pair (scr_tls_ca.c — its own link gate, no
+    // mbedTLS): getCACertificates(type?) answers the per-type cached PEM
+    // string array (an omitted type completes to "default", Node's own
+    // default; unknown strings throw Node's ERR_INVALID_ARG_VALUE at
+    // runtime), and setDefaultCACertificates(certs) replaces the default
+    // set and the client trust anchors. rootCertificates is a VALUE read —
+    // lowerTlsRootCertificates below.
+    if (bi.member === "getCACertificates") {
+        if (args.length > 1) {
+            L.noLowering(`getCACertificates with ${args.length} arguments`, expr);
+        }
+        const typeArg = args.length === 1
+            ? L.lowerExprExpecting(args[0], STRING)
+            : { kind: "strLit", value: "default", type: STRING, loc };
+        return { kind: "libCall", fn: "tlsca.get", args: [typeArg], type: arrayOf(STRING), loc };
+    }
+    if (bi.member === "setDefaultCACertificates") {
+        if (args.length !== 1) {
+            L.noLowering(`setDefaultCACertificates with ${args.length} arguments`, expr);
+        }
+        const certs = L.lowerExpr(args[0]);
+        if (certs.type.kind !== "array" || certs.type.elem.kind !== "string") {
+            L.noLowering(`setDefaultCACertificates of a '${L.fmt(certs.type)}' value`, args[0], "a string[] of PEM certificates is the lowered shape — decode Buffer/typed-array entries to strings first");
+        }
+        return { kind: "libCall", fn: "tlsca.set", args: [certs], type: VOID, loc };
+    }
     L.noLowering(`tls.${bi.member}`, expr, builtinFenceHintOf("tls", bi.member) ??
         "createServer({ cert, key }, handler) and createSecureContext({ cert, key }) are the lowered tls module functions", L.resolveValueSymbol(expr.expression));
 }
+/** The tls.rootCertificates VALUE read (any import spelling): the same
+ * cached array getCACertificates("bundled") answers — Node's own
+ * equality (test-tls-get-ca-certificates-bundled pins certs ===
+ * rootCertificates). Null for other members (the property chains keep
+ * trying). */
+export function lowerTlsRootCertificates(L, bi, loc) {
+    if (bi.module !== "tls" || bi.member !== "rootCertificates")
+        return null;
+    return { kind: "libCall", fn: "tlsca.root", args: [], type: arrayOf(STRING), loc };
+}
 const httpClientFnBindings = new WeakMap();
 export function httpClientFnBindingOf(L, sym) {
     return httpClientFnBindings.get(L)?.get(sym);
@@ -2668,12 +2862,37 @@ function lowerHttp2ModuleCall(L, expr, bi, loc) {
         return { kind: "libCall", fn: "http2.getDefaultSettings", args: [], type: DYN, loc };
     }
     if (bi.member === "createSecureServer") {
-        if (args.length !== 1) {
-            L.noLowering(`createSecureServer with ${args.length} arguments`, expr, "the supported form is createSecureServer({ allowHTTP1: true, cert, key }) — register the handler with server.on(\"request\", (req, res) => ...)");
+        if (args.length < 1 || args.length > 2) {
+            L.noLowering(`createSecureServer with ${args.length} arguments`, expr, "the supported forms are createSecureServer(options[, onRequestHandler]) with options { allowHTTP1?, cert, key }");
         }
         const optsNode = args[0];
+        // The eager (req, res) handler — Node routes it as the first
+        // 'request' listener; both flavors' compat layers serve it (the
+        // allowHTTP1 server's HTTP/1.1 handles, the h2 server's compat
+        // handles over streams).
+        const handlerNode = args.length === 2 ? args[1] : null;
         if (!ts.isObjectLiteralExpression(optsNode)) {
-            L.noLowering("createSecureServer with a non-literal options argument", optsNode, "pass the options as an object literal: { allowHTTP1: true, cert, key }");
+            // The RUNTIME options record (the divergence-66 stance, the
+            // tls/https.createServerDyn precedent): allowHTTP1/cert/key read
+            // at runtime, out-of-bounds TLS members throw the catchable
+            // runtime fence, h2 session-tuning keys drop exactly like the
+            // literal walk ignores them.
+            const v = L.lowerExpr(optsNode);
+            let dynOpts;
+            if (v.type.kind === "dyn") {
+                dynOpts = v;
+            }
+            else if (canConvertToDyn(v.type, (id) => L.shapes.get(id), (id) => L.unions.get(id))) {
+                dynOpts = { kind: "dynFrom", value: v, type: DYN, loc: locOf(optsNode) };
+            }
+            else {
+                L.noLowering("createSecureServer with a non-literal options argument", optsNode, "pass the options as an object literal ({ allowHTTP1: true, cert, key }) or a runtime record of those members");
+            }
+            if (handlerNode === null) {
+                return { kind: "libCall", fn: "http2.createSecureServerDyn", args: [dynOpts], type: NETSERVER_T, loc };
+            }
+            const cb = lowerRequestHandlerArg(L, handlerNode);
+            return { kind: "libCall", fn: "http2.createSecureServerDynCb", args: [dynOpts, cb], type: NETSERVER_T, loc };
         }
         let cert = null;
         let key = null;
@@ -2835,6 +3054,9 @@ function lowerHttp2ModuleCall(L, expr, bi, loc) {
         if (cert === null || key === null) {
             L.noLowering("createSecureServer without both cert and key", optsNode, "the supported options object is { allowHTTP1?, cert, key } (PEM strings or Buffers)");
         }
+        if (sni !== null && handlerNode !== null) {
+            L.noLowering("createSecureServer with both an SNICallback and an eager handler", expr, "register the handler separately: server.on(\"request\", (req, res) => ...)");
+        }
         if (!allowHttp1) {
             // The REAL h2-over-TLS server (scr_http2.c + scr_tls.c): ALPN
             // advertises h2 alone and the h2 session attaches at establishment
@@ -2844,11 +3066,19 @@ function lowerHttp2ModuleCall(L, expr, bi, loc) {
             if (sni !== null) {
                 L.noLowering("createSecureServer with an SNICallback and no allowHTTP1", optsNode, "SNICallback lowers on the allowHTTP1 compatibility server — the ALPN=h2 server serves one cert/key pair");
             }
+            if (handlerNode !== null) {
+                const cb = lowerRequestHandlerArg(L, handlerNode);
+                return { kind: "libCall", fn: "http2.createSecureServerH2Req", args: [cert, key, cb], type: NETSERVER_T, loc };
+            }
             return { kind: "libCall", fn: "http2.createSecureServerH2", args: [cert, key], type: NETSERVER_T, loc };
         }
         if (sni !== null) {
             return { kind: "libCall", fn: "http2.createSecureServerSni", args: [cert, key, sni], type: NETSERVER_T, loc };
         }
+        if (handlerNode !== null) {
+            const cb = lowerRequestHandlerArg(L, handlerNode);
+            return { kind: "libCall", fn: "http2.createSecureServerReq", args: [cert, key, cb], type: NETSERVER_T, loc };
+        }
         return { kind: "libCall", fn: "http2.createSecureServer", args: [cert, key], type: NETSERVER_T, loc };
     }
     L.noLowering(`http2.${bi.member}`, expr, builtinFenceHintOf("http2", bi.member) ??
@@ -2860,8 +3090,8 @@ function lowerHttp2ModuleCall(L, expr, bi, loc) {
  * object literal with string values, or any Record whose values are
  * strings / `string | undefined` — the env.pairs shape). Every other key
  * fences by name. The callback registers as once('response'); get() is
- * request() plus the eager end(). The url-string first argument has no
- * lowering (build the options object instead). `secure` is the https
+ * request() plus the eager end(). A URL-STRING first argument takes the
+ * requestUrl row instead (both schemes; see below). `secure` is the https
  * spelling: port defaults to 443 and the rejectUnauthorized (boolean)
  * and ca (PEM string/Buffer) options join the lowered set. A
  * HttpClientFnBinding as `secure` is the requestFn-binding mode: whether
@@ -2890,22 +3120,38 @@ function lowerHttpClientCall(L, expr, member, loc, secure = false) {
     const optsNode = args[0];
     if (!ts.isObjectLiteralExpression(optsNode)) {
         const t = L.mapTypeOf(L.typeOf(optsNode));
-        if (t?.kind === "string" && !secureish) {
-            // The URL-string form — http.get(`http://127.0.0.1:${port}/x`[, cb]):
-            // the runtime parses through the WHATWG unit and dials; unparsable
-            // inputs and non-http schemes throw catchably (may-throw seed).
-            const url = L.lowerExprExpecting(optsNode, STRING);
+        if ((t?.kind === "string" || t?.kind === "url") && binding === null) {
+            // The URL-string form — http.get(`http://127.0.0.1:${port}/x`[, cb])
+            // and its https spelling: the runtime parses through the WHATWG unit
+            // and dials; unparsable inputs and a scheme that is not the calling
+            // module's throw catchably (may-throw seed). No options means Node's
+            // defaults, which for https is verification against the default
+            // trust anchors. The requestFn binding has no URL row — whether the
+            // dial is TLS is only known at runtime there, and the two schemes
+            // reject each other's URLs.
+            // A URL OBJECT is its href through the same parse — Node's own
+            // reading of the argument, and the serialization round-trips.
+            const url = t.kind === "url"
+                ? { kind: "libCall", fn: "url.href", args: [L.lowerExpr(optsNode)], type: STRING, loc }
+                : L.lowerExprExpecting(optsNode, STRING);
             const methodLit = { kind: "strLit", value: "GET", type: STRING, loc };
             const autoEnd = boolLit(member === "get", loc);
+            const isTls = secure === true;
             if (args.length === 1) {
-                return { kind: "libCall", fn: "http.requestUrl", args: [url, methodLit, autoEnd], type: HTTPCLIENTREQ_T, loc };
+                const fn = isTls ? "https.requestUrl" : "http.requestUrl";
+                return { kind: "libCall", fn, args: [url, methodLit, autoEnd], type: HTTPCLIENTREQ_T, loc };
             }
             const { cb } = lowerCallbackArg(L, args[1], "response callbacks", 1, (p) => p.kind === "httpReq", "use (res) or ()", [HTTPREQ_T]);
-            return { kind: "libCall", fn: "http.requestUrlCb", args: [url, methodLit, autoEnd, cb], type: HTTPCLIENTREQ_T, loc };
+            const fn = isTls ? "https.requestUrlCb" : "http.requestUrlCb";
+            return { kind: "libCall", fn, args: [url, methodLit, autoEnd, cb], type: HTTPCLIENTREQ_T, loc };
         }
         L.noLowering(t?.kind === "string"
-            ? `${member} with a URL-string first argument`
-            : `${member} with a non-literal options argument`, optsNode, "pass the options as an object literal: { hostname, port, path, method, timeout?, headers? }");
+            ? `a URL-string first argument through a request-function binding`
+            : `${member} with a non-literal options argument`, optsNode, t?.kind === "string"
+            // Only the binding mode reaches here now: the scheme would have to
+            // agree with a dial chosen at runtime.
+            ? "call http.request / https.request directly for the URL-string form, or pass the options as an object literal"
+            : "pass the options as an object literal: { hostname, port, path, method, timeout?, headers? }");
     }
     let host = null;
     let port = null;
@@ -2918,6 +3164,8 @@ function lowerHttpClientCall(L, expr, member, loc, secure = false) {
     let connCb = null;
     /** agent: false — inject Connection: close into the request head. */
     let agentClose = null;
+    /** agent: <Agent value> — the requestAgent rows thread the handle. */
+    let agentVal = null;
     for (const prop of optsNode.properties) {
         // Shorthand entries ({ port } for { port: port }) are the natural
         // spelling at these call sites — the shorthand's VALUE lowering
@@ -3055,8 +3303,11 @@ function lowerHttpClientCall(L, expr, member, loc, secure = false) {
                 // model, so it LOWERS (the header injects below). null/undefined
                 // pick the default agent, whose keep-alive request header the
                 // compiled client already sends (socket REUSE stays the
-                // documented divergence either way). Agent instances configure
-                // pooling the runtime does not have — fence.
+                // documented divergence either way). An Agent VALUE (the lowered
+                // `new http.Agent(...)` handle — a checked-dynamic value) threads
+                // through the requestAgent rows: getName-keyed maxSockets
+                // accounting over one-dial-per-request connections; a runtime
+                // non-Agent value is Node's ERR_INVALID_ARG_TYPE.
                 const e = initializer !== null ? stripParensAndCasts(initializer) : null;
                 if (e !== null && e.kind === ts.SyntaxKind.FalseKeyword) {
                     agentClose = prop;
@@ -3067,9 +3318,14 @@ function lowerHttpClientCall(L, expr, member, loc, secure = false) {
                         (ts.isIdentifier(e) && e.text === "undefined"))) {
                     break; // the default agent: what the agent-free call compiles
                 }
-                L.noLowering(`a ${member} 'agent' option carrying an Agent value`, prop, "compiled clients dial one connection per request and close it with the response — " +
-                    "agent: false (lowered: sends Connection: close) and agent: null/undefined (the default) " +
-                    "compile; pooling Agent instances have no lowering");
+                const v = initializer !== null
+                    ? L.lowerExpr(initializer)
+                    : L.lowerShorthandValue(prop);
+                if (v.type.kind !== "dyn") {
+                    L.noLowering(`a ${member} 'agent' option of '${L.fmt(v.type)}' values`, prop, "the agent is the checked-dynamic Agent handle new http.Agent(...) answers " +
+                        "(or false / null / undefined)");
+                }
+                agentVal = v;
                 break;
             }
             default:
@@ -3107,12 +3363,21 @@ function lowerHttpClientCall(L, expr, member, loc, secure = false) {
         // exists — a silent half-use; set headers.host instead.
         L.noLowering(`${member} mixing createConnection with hostname/host/port`, optsNode, "the dialer supplies the socket — set the Host header via headers: { host: ... } instead");
     }
+    if (agentVal !== null && connCb !== null) {
+        L.noLowering(`${member} mixing an agent value with createConnection`, optsNode, "both own the dial — pass one or the other");
+    }
+    if (agentVal !== null && binding !== null) {
+        L.noLowering(`${member} through a module-function binding with an agent value`, optsNode, "call http.request/https.request directly when passing an Agent");
+    }
     host ??= strLit("localhost");
     // The binding mode's default port follows the runtime dial: 443 on the
     // TLS arm, 80 on the plain one — exactly each client's own default.
+    // With an AGENT the sentinel -1 says "no port option": the runtime
+    // consults the agent's (settable) defaultPort first, Node's merge.
     port ??= binding !== null
         ? { kind: "ternary", cond: secureExpr(), then: numLit(443), else_: numLit(80), type: F64, loc }
-        : numLit(secure === true ? 443 : 80);
+        : agentVal !== null ? numLit(-1)
+            : numLit(secure === true ? 443 : 80);
     path ??= strLit("/");
     method ??= strLit("GET");
     timeout ??= numLit(0);
@@ -3132,14 +3397,20 @@ function lowerHttpClientCall(L, expr, member, loc, secure = false) {
         ca ??= strLit(""); /* none: /etc/ssl/cert.pem stands in for Node's roots */
         base.push(reject, ca);
     }
+    if (agentVal !== null)
+        base.push(agentVal);
     if (binding !== null)
         base.unshift(secureExpr());
     if (args.length === 1) {
-        const fn = binding !== null ? "https.requestFn" : secure === true ? "https.request" : "http.request";
+        const fn = binding !== null ? "https.requestFn"
+            : secure === true ? (agentVal !== null ? "https.requestAgent" : "https.request")
+                : agentVal !== null ? "http.requestAgent" : "http.request";
         return { kind: "libCall", fn, args: base, type: HTTPCLIENTREQ_T, loc };
     }
     const { cb } = lowerCallbackArg(L, args[1], "response callbacks", 1, (p) => p.kind === "httpReq", "use (res) or ()", [HTTPREQ_T]);
-    const fn = binding !== null ? "https.requestFnCb" : secure === true ? "https.requestCb" : "http.requestCb";
+    const fn = binding !== null ? "https.requestFnCb"
+        : secure === true ? (agentVal !== null ? "https.requestAgentCb" : "https.requestCb")
+            : agentVal !== null ? "http.requestAgentCb" : "http.requestCb";
     return { kind: "libCall", fn, args: [...base, cb], type: HTTPCLIENTREQ_T, loc };
 }
 /** The headers option of http.request: an object literal with literal