@forklaunch/core 3.2.1 → 3.4.0

package/lib/http/index.js

@@ -66,10 +66,12 @@ __export(http_exports, {
   auditComplianceAccess: () => auditComplianceAccess,
   auditEnabled: () => auditEnabled,
   auditEventType: () => auditEventType,
+  bindRuntimeAuth: () => bindRuntimeAuth,
   createContext: () => createContext,
   createEmailClient: () => createEmailClient,
   createHmacToken: () => createHmacToken,
   createInstanceGatewayTransport: () => createInstanceGatewayTransport,
+  createLocalModelGatewayClient: () => createLocalModelGatewayClient,
   createModelGatewayClient: () => createModelGatewayClient,
   createPaymentsClient: () => createPaymentsClient,
   createPreviewModelGatewayClient: () => createPreviewModelGatewayClient,
@@ -119,6 +121,7 @@ __export(http_exports, {
   put: () => put,
   recordMetric: () => recordMetric,
   recordRequestAudit: () => recordRequestAudit,
+  registerDelegatedSurface: () => registerDelegatedSurface,
   resetProcessHandlersForTesting: () => resetProcessHandlersForTesting,
   signPlatformEvent: () => signPlatformEvent,
   smsSegments: () => smsSegments,
@@ -134,6 +137,68 @@ __export(http_exports, {
 });
 module.exports = __toCommonJS(http_exports);
 
+// src/http/bindRuntimeAuth.ts
+function bindRuntimeAuth(details, binding) {
+  const policy = { ...details.auth };
+  const keys = Object.keys(binding);
+  const credentials = { ...binding };
+  const invalid = () => {
+    throw new Error("Invalid runtime authentication binding");
+  };
+  const allowedPolicy = policy.scheme === "jwt" ? [
+    "scheme",
+    "headerName",
+    "tokenPrefix",
+    "sessionSchema",
+    "allowedRoles",
+    "allowedPermissions"
+  ] : ["scheme", "headerName", "tokenPrefix"];
+  if (Object.keys(policy).some((key) => !allowedPolicy.includes(key)))
+    invalid();
+  for (const key of ["headerName", "tokenPrefix"]) {
+    if (policy[key] !== void 0 && (typeof policy[key] !== "string" || !policy[key]))
+      invalid();
+  }
+  if (policy.scheme === "jwt" && policy.allowedRoles === void 0 && policy.allowedPermissions === void 0)
+    invalid();
+  let authentication;
+  if (policy.scheme === "jwt") {
+    if (keys.some(
+      (key) => !["jwksPublicKeyUrl", "signatureKey", "decodeResource"].includes(key)
+    ))
+      invalid();
+    const keyFields = keys.filter((key) => key !== "decodeResource");
+    if (keyFields.length !== 1 || typeof credentials[keyFields[0]] !== "string" || !credentials[keyFields[0]])
+      invalid();
+    const decodeResource = credentials.decodeResource;
+    if (decodeResource !== void 0 && typeof decodeResource !== "function")
+      invalid();
+    delete credentials.decodeResource;
+    authentication = {
+      jwt: credentials,
+      ...decodeResource === void 0 ? {} : { decodeResource }
+    };
+  } else if (policy.scheme === "hmac") {
+    if (keys.length !== 1 || keys[0] !== "secretKeys" || !credentials.secretKeys || typeof credentials.secretKeys !== "object" || Array.isArray(credentials.secretKeys) || Object.keys(credentials.secretKeys).length === 0 || Object.values(credentials.secretKeys).some(
+      (key) => typeof key !== "string" || !key
+    ))
+      invalid();
+    authentication = { hmac: credentials };
+  } else {
+    return invalid();
+  }
+  delete policy.scheme;
+  for (const key of ["allowedRoles", "allowedPermissions"]) {
+    if (policy[key] !== void 0) {
+      const values = policy[key];
+      if (!Array.isArray(values) || values.some((value) => typeof value !== "string"))
+        invalid();
+      policy[key] = new Set(values);
+    }
+  }
+  return { ...details, auth: { ...policy, ...authentication } };
+}
+
 // src/http/middleware/request/cors.middleware.ts
 var import_cors = __toESM(require("cors"));
 function cors(corsOptions) {
@@ -594,7 +659,7 @@ function createContext(schemaValidator) {
 }
 
 // src/http/router/discriminateBody.ts
-function discriminateBody(schemaValidator, body) {
+function discriminateBody(schemaValidator, body, inputProjection) {
   if (body == null) {
     return void 0;
   }
@@ -644,7 +709,7 @@ function discriminateBody(schemaValidator, body) {
       parserType: "text",
       schema: maybeTypedBody
     };
-  } else if (schemaValidator.openapi(maybeTypedBody).format === "binary") {
+  } else if ((inputProjection ?? schemaValidator.openapi(maybeTypedBody)).format === "binary") {
     return {
       contentType: "application/octet-stream",
       parserType: "file",
@@ -1074,15 +1139,23 @@ async function checkAuthorizationToken(req, authorizationMethod, authorizationTo
       if (!parsedKeyId || !parsedTimestamp || !parsedNonce || !parsedSignature) {
         return invalidAuthorizationTokenFormat;
       }
-      const verificationResult = await auth.verificationFunction({
-        method: req?.method ?? "",
-        path: req?.path ?? "",
-        body: req?._rawBody ?? req?.body,
-        timestamp: new Date(parsedTimestamp),
-        nonce: parsedNonce,
-        signature: parsedSignature,
-        secretKey: collapsedAuthorizationMethod.hmac.secretKeys[parsedKeyId]
-      });
+      let verificationResult = false;
+      const signedPaths = hmacSignedPaths(req);
+      for (const path of signedPaths) {
+        verificationResult = Boolean(await auth.verificationFunction({
+          method: req?.method ?? "",
+          path,
+          body: req?._rawBody ?? req?.body,
+          timestamp: new Date(parsedTimestamp),
+          nonce: parsedNonce,
+          signature: parsedSignature,
+          secretKey: collapsedAuthorizationMethod.hmac.secretKeys[parsedKeyId]
+        }));
+        if (verificationResult) {
+          if (path !== signedPaths[0]) warnMountRelativeHmacPath();
+          break;
+        }
+      }
       if (!verificationResult) {
         return invalidAuthorizationSignature;
       }
@@ -1249,6 +1322,25 @@ async function checkAuthorizationToken(req, authorizationMethod, authorizationTo
     }
   }
 }
+function acceptMountRelativeHmacPaths() {
+  const value = typeof process === "undefined" ? void 0 : process.env?.HMAC_ACCEPT_MOUNT_RELATIVE_PATHS;
+  return value == null || !["false", "0"].includes(value.trim().toLowerCase());
+}
+var warnedMountRelativeHmacPath = false;
+function warnMountRelativeHmacPath() {
+  if (warnedMountRelativeHmacPath) return;
+  warnedMountRelativeHmacPath = true;
+  console.warn(
+    "Accepted an HMAC signature over the router-relative path. Sign the full request path instead; set HMAC_ACCEPT_MOUNT_RELATIVE_PATHS=false to reject the deprecated form."
+  );
+}
+function hmacSignedPaths(req) {
+  const relative = req?.path ?? "";
+  const wire = (req?.originalUrl ?? req?.url ?? relative).split("?")[0] || relative;
+  const paths = [wire];
+  if (relative !== wire && acceptMountRelativeHmacPaths()) paths.push(relative);
+  return paths;
+}
 async function parseRequestAuth(req, res, next) {
   const access = req.contractDetails.access;
   if (access === "public") {
@@ -1482,6 +1574,21 @@ function isRequestShape(maybeResponseShape) {
   return maybeResponseShape != null && ("body" in maybeResponseShape || "query" in maybeResponseShape || "params" in maybeResponseShape || "headers" in maybeResponseShape);
 }
 
+// src/http/middleware/internal/validationDiagnostic.ts
+var sendingDiagnostics = /* @__PURE__ */ new WeakSet();
+function isValidationDiagnostic(response) {
+  return sendingDiagnostics.has(response);
+}
+function sendValidationDiagnostic(response, send) {
+  const alreadySending = sendingDiagnostics.has(response);
+  sendingDiagnostics.add(response);
+  try {
+    return send();
+  } finally {
+    if (!alreadySending) sendingDiagnostics.delete(response);
+  }
+}
+
 // src/http/middleware/request/parse.middleware.ts
 function parse(req, res, next) {
   const globalOptions = req._globalOptions?.();
@@ -1563,14 +1670,13 @@ function parse(req, res, next) {
       default:
       case void 0:
       case "error":
-        res.type("application/json");
+        res.type("text/plain");
         res.status(400);
         if (hasSend(res)) {
-          res.send(
-            `${collectedParseErrors ?? (0, import_validator2.prettyPrintParseErrors)(parsedRequest.errors, "Request")}
+          const diagnostic = `${collectedParseErrors ?? (0, import_validator2.prettyPrintParseErrors)(parsedRequest.errors, "Request")}
 
-Correlation id: ${req.context.correlationId ?? "No correlation ID"}`
-          );
+Correlation id: ${req.context.correlationId ?? "No correlation ID"}`;
+          sendValidationDiagnostic(res, () => res.send(diagnostic));
         } else {
           next?.(new Error("Request is not sendable."));
         }
@@ -1979,13 +2085,25 @@ var ForklaunchExpressLikeRouter = class _ForklaunchExpressLikeRouter {
           span: void 0
         },
         _rawBody: void 0,
-        _parsedVersions: void 0
+        _parsedVersions: void 0,
+        // hyper-express's content parser reads the body through its Request's
+        // body readers; serve the body the call was given.
+        buffer: async () => Buffer.from(
+          typeof req.body === "string" ? req.body : JSON.stringify(req.body)
+        ),
+        json: async () => req.body,
+        text: async () => typeof req.body === "string" ? req.body : JSON.stringify(req.body)
       };
       const res = {
         statusCode: 200,
+        // hyper-express's response enrichment reads the status and headers
+        // from these fields, which its own Response keeps.
+        _status_code: 200,
+        _headers: responseHeaders,
         status: (code) => {
           statusCode = code;
           res.statusCode = code;
+          res._status_code = code;
           return res;
         },
         send: (message) => {
@@ -2005,6 +2123,8 @@ var ForklaunchExpressLikeRouter = class _ForklaunchExpressLikeRouter {
           return res;
         },
         getHeader: (key) => responseHeaders[key],
+        getHeaders: () => ({ ...responseHeaders }),
+        locals: {},
         type: (contentType) => {
           responseHeaders["content-type"] = contentType;
           return res;
@@ -2023,31 +2143,59 @@ var ForklaunchExpressLikeRouter = class _ForklaunchExpressLikeRouter {
         version
       };
       const executeMiddlewares = request?.executeMiddlewares ?? false;
+      const cHandler = controllerHandler;
       if (executeMiddlewares && middlewares.length > 0) {
-        const allHandlers = [...middlewares];
-        let cursor = allHandlers.shift();
-        if (cursor) {
-          for (const fn of allHandlers) {
-            await cursor(req, res, (err) => {
-              if (err) {
-                throw err;
+        const chain = middlewares;
+        await new Promise((resolve, reject) => {
+          let settled = false;
+          let responded = false;
+          let controllerStarted = false;
+          const finish = (error) => {
+            if (settled) return;
+            settled = true;
+            if (error) reject(error);
+            else resolve();
+          };
+          res.on("finish", () => {
+            responded = true;
+            if (!controllerStarted) finish();
+          });
+          const run = async (index) => {
+            try {
+              if (index === chain.length) {
+                controllerStarted = true;
+                await cHandler(req, res, (err) => {
+                  if (err) {
+                    throw err;
+                  }
+                });
+                finish();
+                return;
               }
-              cursor = fn;
-            });
-          }
-          await cursor(req, res, async (err) => {
-            if (err) {
-              throw err;
+              let calledNext = false;
+              await chain[index](req, res, (err) => {
+                calledNext = true;
+                if (err) {
+                  throw err;
+                }
+                return run(index + 1);
+              });
+              if (!calledNext && chain[index].length < 3 && !responded) {
+                await run(index + 1);
+              }
+            } catch (error) {
+              finish(error);
             }
-          });
-        }
+          };
+          void run(0);
+        });
+      } else {
+        await cHandler(req, res, (err) => {
+          if (err) {
+            throw err;
+          }
+        });
       }
-      const cHandler = controllerHandler;
-      await cHandler(req, res, (err) => {
-        if (err) {
-          throw err;
-        }
-      });
       return {
         code: Number(statusCode),
         response: responseMessage,
@@ -2831,12 +2979,55 @@ function signPlatformEvent(params) {
   });
 }
 
+// src/http/modelStream.ts
+async function* readModelStream(response) {
+  const reader = response.body?.getReader();
+  if (!reader)
+    throw new ModelGatewayRequestError(502, "The model stream is empty.");
+  const decoder = new TextDecoder();
+  let buffer = "", bytes = 0;
+  try {
+    for (; ; ) {
+      const part = await reader.read();
+      if (part.done) break;
+      bytes += part.value.byteLength;
+      if (bytes > 512e3) throw new Error("oversized");
+      buffer += decoder.decode(part.value, { stream: true });
+      let match;
+      while (match = buffer.match(/\r?\n\r?\n/)) {
+        const event = buffer.slice(0, match.index);
+        buffer = buffer.slice(match.index + match[0].length);
+        const data = event.split(/\r?\n/).filter((line) => line.startsWith("data:")).map((line) => line.slice(5).trimStart()).join("\n");
+        if (!data) continue;
+        if (data === "[DONE]") return;
+        const value = JSON.parse(data);
+        if (value.error || !Array.isArray(value.choices))
+          throw new Error("invalid");
+        yield value;
+      }
+    }
+    throw new Error("interrupted");
+  } catch {
+    throw new ModelGatewayRequestError(
+      502,
+      "The model stream was interrupted. No automatic retry was sent."
+    );
+  } finally {
+    await reader.cancel().catch(() => {
+    });
+    reader.releaseLock();
+  }
+}
+
 // src/http/modelGatewayClient.ts
 var ModelGatewayRequestError = class extends InstanceGatewayRequestError {
   name = "ModelGatewayRequestError";
 };
 function createModelGatewayClient(options2 = {}) {
-  const transport = createInstanceGatewayTransport(options2, "The model gateway");
+  const transport = createInstanceGatewayTransport(
+    options2,
+    "The model gateway"
+  );
   async function send(method, route, body, signal) {
     try {
       return await transport.request(method, route, body, { signal });
@@ -2872,42 +3063,12 @@ function createModelGatewayClient(options2 = {}) {
             request,
             streamOptions.signal
           );
-          if (!response.body) return;
-          for await (const data of sseData(response.body)) {
-            if (data === "[DONE]") return;
-            try {
-              yield JSON.parse(data);
-            } catch {
-            }
-          }
+          yield* readModelStream(response);
         }
       }
     }
   };
 }
-async function* sseData(stream) {
-  const decoder = new TextDecoder();
-  let buffer = "";
-  const reader = stream.getReader();
-  try {
-    for (; ; ) {
-      const { value, done } = await reader.read();
-      if (done) break;
-      buffer += decoder.decode(value, { stream: true });
-      let boundary;
-      while ((boundary = buffer.search(/\r?\n\r?\n/)) !== -1) {
-        const event = buffer.slice(0, boundary);
-        buffer = buffer.slice(boundary).replace(/^\r?\n\r?\n/, "");
-        const data = event.split(/\r?\n/).filter((line) => line.startsWith("data:")).map((line) => line.slice(5).trimStart()).join("\n");
-        if (data) yield data;
-      }
-    }
-    const tail = buffer.trim();
-    if (tail.startsWith("data:")) yield tail.slice(5).trimStart();
-  } finally {
-    reader.releaseLock();
-  }
-}
 
 // src/http/previewModelGatewayClient.ts
 function record(value) {
@@ -2963,9 +3124,9 @@ function createPreviewModelGatewayClient(options2 = {}) {
     options2,
     "The local preview model gateway"
   );
-  async function send(method, route, body) {
+  async function send(method, route, body, signal) {
     try {
-      return await transport.request(method, route, body);
+      return await transport.request(method, route, body, { signal });
     } catch (error) {
       if (error instanceof InstanceGatewayRequestError)
         throw new ModelGatewayRequestError(
@@ -2983,6 +3144,15 @@ function createPreviewModelGatewayClient(options2 = {}) {
     },
     chat: {
       completions: {
+        async *stream(request, options3 = {}) {
+          const response = await send(
+            "POST",
+            "/models/chat/completions",
+            { ...request, stream: true },
+            options3.signal
+          );
+          yield* readModelStream(response);
+        },
         async create(request) {
           return await (await send(
             "POST",
@@ -3517,6 +3687,19 @@ function createPaymentsClient(options2 = {}) {
     },
     status() {
       return call("GET", "/payments/status");
+    },
+    payouts(params = {}) {
+      const { limit } = params;
+      if (limit !== void 0 && (!Number.isInteger(limit) || limit < 1 || limit > 50)) {
+        throw new TypeError("limit must be a whole number from 1 to 50");
+      }
+      return call(
+        "GET",
+        limit === void 0 ? "/payments/payouts" : `/payments/payouts?limit=${limit}`
+      );
+    },
+    dashboardLink() {
+      return call("POST", "/payments/dashboard-link", {});
     }
   };
 }
@@ -3536,7 +3719,7 @@ function loadStripe() {
 function stripeGatewayFetch(settings, fetchImpl = fetch) {
   const base = new URL(settings.gatewayUrl);
   const basePath = base.pathname.replace(/\/+$/, "");
-  return async (input, init = {}) => {
+  const signedFetch = async (input, init = {}) => {
     const original = new URL(
       typeof input === "string" || input instanceof URL ? input : input.url
     );
@@ -3576,6 +3759,13 @@ function stripeGatewayFetch(settings, fetchImpl = fetch) {
       }
     );
   };
+  const preconnect = Reflect.get(fetchImpl, "preconnect");
+  if (typeof preconnect === "function") {
+    Object.defineProperty(signedFetch, "preconnect", {
+      value: (_input, options2) => Reflect.apply(preconnect, fetchImpl, [base.origin, options2])
+    });
+  }
+  return signedFetch;
 }
 function createStripeClient(options2 = {}) {
   const StripeClass = options2.Stripe ?? loadStripe();
@@ -3594,8 +3784,8 @@ function createStripeClient(options2 = {}) {
     return new StripeClass(options2.apiKey, options2.config);
   }
   const settings = instanceGatewaySettings(options2, "Payments");
-  const gateway = new URL(settings.gatewayUrl);
-  const protocol = gateway.protocol === "http:" ? "http" : "https";
+  const gateway2 = new URL(settings.gatewayUrl);
+  const protocol = gateway2.protocol === "http:" ? "http" : "https";
   return new StripeClass(
     // No key: the authenticator below replaces it, and the gateway holds the
     // real one. (stripe-node accepts an authenticator in place of a key.)
@@ -3603,8 +3793,8 @@ function createStripeClient(options2 = {}) {
     {
       maxNetworkRetries: 2,
       ...options2.config,
-      host: gateway.hostname,
-      port: gateway.port || (protocol === "http" ? 80 : 443),
+      host: gateway2.hostname,
+      port: gateway2.port || (protocol === "http" ? 80 : 443),
       protocol,
       telemetry: false,
       // The signed fetch sets `authorization`; nothing else may.
@@ -4808,10 +4998,10 @@ function generateMcpServer(schemaValidator, protocol, host, port, version, appli
             let bodySchema;
             let responsesSchemas;
             if (route.contractDetails.versions) {
-              const version2 = route.contractDetails.versions[index];
+              const version2 = Object.values(route.contractDetails.versions)[index];
+              responsesSchemas = version2.responses;
               if (version2.body && schemaValidator.parse(inputSchema, args).ok) {
                 bodySchema = version2.body;
-                responsesSchemas = version2.responses;
               }
             } else {
               bodySchema = route.contractDetails.body;
@@ -4822,7 +5012,7 @@ function generateMcpServer(schemaValidator, protocol, host, port, version, appli
             if (discriminatedBody) {
               switch (discriminatedBody.parserType) {
                 case "json": {
-                  parsedBody = (0, import_common13.safeStringify)(body);
+                  parsedBody = body === void 0 ? void 0 : JSON.stringify(body);
                   break;
                 }
                 case "text": {
@@ -4888,11 +5078,11 @@ function generateMcpServer(schemaValidator, protocol, host, port, version, appli
               ).toString();
               url += queryString ? `?${queryString}` : "";
             }
-            const response = await fetch(encodeURI(url), {
+            const response = await fetch(url, {
               method: route.method.toUpperCase(),
               headers: {
                 ...headers,
-                ...discriminatedBody?.contentType != "multipart/form-data" ? {
+                ...discriminatedBody?.contentType != "multipart/form-data" && (contentType ?? discriminatedBody?.contentType) !== void 0 ? {
                   "Content-Type": contentType ?? discriminatedBody?.contentType
                 } : {}
               },
@@ -4970,7 +5160,12 @@ function isResponseCompiledSchema(schema) {
 }
 
 // src/http/middleware/response/parse.middleware.ts
+var sendingValidationError = /* @__PURE__ */ new WeakSet();
 function parse2(req, res, next) {
+  if (sendingValidationError.has(res)) {
+    next?.();
+    return;
+  }
   let headers;
   let responses;
   const globalOptions = req._globalOptions?.();
@@ -5013,15 +5208,35 @@ function parse2(req, res, next) {
     responses = responseSchemas.responses;
   }
   const statusCode = Number(res.statusCode);
-  const parsedResponse = schemaValidator.parse(
-    [400, 401, 404, 403, 500].includes(statusCode) ? schemaValidator.union([schemaValidator.string, responses?.[statusCode]]) : responses?.[statusCode],
-    res.bodyData
-  );
+  const defaultErrorStatus = [400, 401, 404, 403, 500].includes(statusCode);
+  const missingResponseSchema = !defaultErrorStatus && !Object.prototype.hasOwnProperty.call(responses, statusCode);
+  if (missingResponseSchema && collapsedOptions !== "warning") {
+    throw new Error(`Undocumented response status ${statusCode}`);
+  }
+  const declaredResponse = responses?.[statusCode];
+  const defaultErrorResponse = () => {
+    try {
+      return schemaValidator.parse(
+        schemaValidator.union([schemaValidator.string, declaredResponse]),
+        res.bodyData
+      );
+    } catch (error) {
+      if (declaredResponse === void 0) throw error;
+      const declared = schemaValidator.parse(declaredResponse, res.bodyData);
+      if (declared.ok) return declared;
+      const message = schemaValidator.parse(
+        schemaValidator.string,
+        res.bodyData
+      );
+      return message.ok ? message : declared;
+    }
+  };
+  const parsedResponse = missingResponseSchema ? { ok: true } : defaultErrorStatus ? defaultErrorResponse() : schemaValidator.parse(declaredResponse, res.bodyData);
   const parsedHeaders = schemaValidator.parse(
     headers ?? schemaValidator.unknown,
     res.getHeaders()
   );
-  const parseErrors = [];
+  const parseErrors = missingResponseSchema ? [`Response: Undocumented response status ${statusCode}`] : [];
   if (!parsedHeaders.ok) {
     const headerErrors = (0, import_validator3.prettyPrintParseErrors)(parsedHeaders.errors, "Header");
     if (headerErrors) {
@@ -5038,21 +5253,26 @@ function parse2(req, res, next) {
     }
   }
   if (parseErrors.length > 0) {
-    switch (req.contractDetails.options?.responseValidation) {
+    switch (collapsedOptions) {
       default:
       case void 0:
       case "error":
         res.type("text/plain");
         res.status(500);
         if (hasSend(res)) {
-          res.send(
-            `Invalid response:
+          sendingValidationError.add(res);
+          try {
+            res.send(
+              `Invalid response:
 ${parseErrors.join(
-              "\n\n"
-            )}
+                "\n\n"
+              )}
 
 Correlation id: ${req.context.correlationId ?? "No correlation ID"}`
-          );
+            );
+          } finally {
+            sendingValidationError.delete(res);
+          }
         } else {
           next?.(new Error("Response is not sendable."));
         }
@@ -5063,8 +5283,6 @@ Correlation id: ${req.context.correlationId ?? "No correlation ID"}`
 ${parseErrors.join("\n\n")}`
         );
         break;
-      case "none":
-        break;
     }
   }
   next?.();
@@ -5106,6 +5324,10 @@ function enrichExpressLikeSend(instance, req, res, originalOperation, originalSe
     originalSend.call(instance, data);
     return;
   }
+  if (typeof data === "string" && isValidationDiagnostic(res)) {
+    originalSend.call(instance, data);
+    return;
+  }
   let responses;
   if (req.contractDetails.responses == null && (req.contractDetails.versions == null || Object.values(req.contractDetails.versions).some(
     (version) => version?.responses == null
@@ -5115,7 +5337,7 @@ function enrichExpressLikeSend(instance, req, res, originalOperation, originalSe
     if (req.contractDetails.responses != null) {
       responses = req.contractDetails.responses;
     } else {
-      responses = req.contractDetails.versions[req.version].responses;
+      responses = req.contractDetails.versions[req.version]?.responses ?? {};
     }
   }
   const responseBodies = discriminateResponseBodies(
@@ -5337,7 +5559,16 @@ function generateOperationObject(schemaValidator, path, method, controllerName,
   for (const key in discriminatedResponseBodiesResult) {
     coercedResponses[key] = {
       description: httpStatusCodes_default[key],
-      content: contentResolver(
+      // Undefined/void represent no response body, not a JSON null payload.
+      // Check the schema kind rather than its OpenAPI projection: null and
+      // nullish also project to null but still admit an actual JSON body.
+      content: schemaValidator.undefined !== void 0 && typedSchemaValidator.isInstanceOf(
+        discriminatedResponseBodiesResult[key].schema,
+        schemaValidator.undefined
+      ) || schemaValidator.void !== void 0 && typedSchemaValidator.isInstanceOf(
+        discriminatedResponseBodiesResult[key].schema,
+        schemaValidator.void
+      ) ? void 0 : contentResolver(
         schemaValidator,
         discriminatedResponseBodiesResult[key].schema,
         discriminatedResponseBodiesResult[key].contentType
@@ -5373,15 +5604,21 @@ function generateOperationObject(schemaValidator, path, method, controllerName,
       operationObject.parameters?.push({
         name: key,
         in: "path",
+        required: true,
         schema: typedSchemaValidator.openapi(params[key])
       });
     }
   }
-  const discriminatedBodyResult = body ? discriminateBody(schemaValidator, body) : null;
+  const adapter = schemaValidator;
+  const bareProjection = body && adapter.isSchema(body) ? adapter.openapiRequestBody?.(body) : void 0;
+  const discriminatedBodyResult = body ? discriminateBody(schemaValidator, body, bareProjection?.schema) : null;
   if (discriminatedBodyResult) {
+    const projection = bareProjection ?? adapter.openapiRequestBody?.(discriminatedBodyResult.schema);
     operationObject.requestBody = {
-      required: true,
-      content: contentResolver(
+      required: projection?.required ?? true,
+      content: projection ? {
+        [discriminatedBodyResult.contentType]: { schema: projection.schema }
+      } : contentResolver(
         schemaValidator,
         discriminatedBodyResult.schema,
         discriminatedBodyResult.contentType
@@ -5416,25 +5653,14 @@ function generateOperationObject(schemaValidator, path, method, controllerName,
       content: contentResolver(schemaValidator, schemaValidator.string)
     };
     if ("basic" in auth) {
-      operationObject.security = [
-        {
-          basic: Array.from(
-            "allowedPermissions" in auth && auth.allowedPermissions instanceof Set ? auth.allowedPermissions.values() : []
-          )
-        }
-      ];
+      operationObject.security = [{ basic: [] }];
       securitySchemes["basic"] = {
         type: "http",
         scheme: "basic"
       };
     } else if (auth) {
-      operationObject.security = [
-        {
-          [auth.headerName !== "Authorization" ? "bearer" : "apiKey"]: Array.from(
-            "allowedPermissions" in auth && auth.allowedPermissions instanceof Set ? auth.allowedPermissions.values() : []
-          )
-        }
-      ];
+      const schemeName = auth.headerName || "Authorization";
+      operationObject.security = [{ [schemeName]: [] }];
       if (auth.headerName && auth.headerName !== "Authorization") {
         securitySchemes[auth.headerName] = {
           type: "apiKey",
@@ -5665,6 +5891,150 @@ var RateLimiter = class {
     return READ_METHODS.has(method.toUpperCase()) ? "read" : "write";
   }
 };
+
+// src/http/registerDelegatedSurface.ts
+function registerDelegatedSurface(surface, mount, register) {
+  if (!surface.id || !surface.provider || surface.coverage !== "provider-owned" || !surface.client.package || !surface.client.export || surface.runtime.basePath !== "runtime-resolved" || typeof surface.runtime.openApi !== "boolean" || !Array.isArray(surface.callbacks) || surface.callbacks.some(
+    (callback) => typeof callback !== "string" || !callback.startsWith("/")
+  )) {
+    throw new Error("Invalid delegated HTTP surface descriptor");
+  }
+  const paths = Array.isArray(mount.paths) ? mount.paths : [mount.paths];
+  if (mount.basePath !== "" && !mount.basePath.startsWith("/") || paths.length === 0 || paths.some(
+    (path) => !path.startsWith("/") || mount.basePath !== "" && !path.startsWith(mount.basePath + "/")
+  )) {
+    throw new Error("Invalid delegated HTTP surface mount");
+  }
+  return register(mount);
+}
+
+// src/http/localModelGatewayClient.ts
+var import_node_child_process = require("child_process");
+var import_node_util = require("util");
+var execute = (0, import_node_util.promisify)(import_node_child_process.execFile);
+var gateway = "https://studio-orchestrator.forklaunch.com/studio-orchestrator/desktop-runtime-model-gateway";
+function validate(value) {
+  if (!value || !/^[a-f0-9]{64}$/.test(value.grantId) || !/^[a-f0-9]{64}$/.test(value.capability) || value.gatewayBaseUrl !== `${gateway}/${value.grantId}/v1` || value.scope !== "local-runtime" || !Number.isSafeInteger(value.expiresAt) || value.expiresAt <= Date.now() || value.expiresAt > Date.now() + 9e5 || !/^[A-Za-z0-9._-]{1,128}$/.test(value.model) || !Number.isInteger(value.maxCalls) || value.maxCalls < 1 || value.maxCalls > 20 || !Number.isInteger(value.maxUnits) || value.maxUnits < 1 || value.maxUnits > 1e5) {
+    throw new Error(
+      "Invalid local model connection. No model request was sent."
+    );
+  }
+  return value;
+}
+function createLocalModelGatewayClient(options2 = {}) {
+  if (process.env.FORKLAUNCH_API_KEY === void 0 && !options2.credentialProvider && process.env.FORKLAUNCH_LOCAL_MODEL_RELAY === "1") {
+    return createPreviewModelGatewayClient({ fetch: options2.fetch });
+  }
+  const applicationId = options2.applicationId ?? process.env.FORKLAUNCH_APPLICATION_ID;
+  const model = options2.model ?? process.env.AGENT_MODEL;
+  if (applicationId && !/^[a-f0-9-]{36}$/i.test(applicationId)) {
+    throw new Error(
+      "FORKLAUNCH_APPLICATION_ID must be a saved application UUID."
+    );
+  }
+  const provider = options2.credentialProvider ?? (async () => {
+    const args = ["model", "credential", "--json"];
+    if (applicationId) args.push("--application-id", applicationId);
+    if (model) args.push("--model", model);
+    try {
+      const { stdout } = await execute("forklaunch", args, {
+        timeout: 35e3,
+        maxBuffer: 65536,
+        windowsHide: true
+      });
+      return JSON.parse(stdout);
+    } catch {
+      throw new Error(
+        "Could not connect the local agent. Run forklaunch login, check app access, and use a CLI that supports model credential."
+      );
+    }
+  });
+  const optionsFetch = options2.fetch ?? fetch;
+  let pending;
+  let credential;
+  async function connection() {
+    if (credential && credential.expiresAt > Date.now()) return credential;
+    pending ??= provider().then(validate).then((value) => credential = value).finally(() => {
+      pending = void 0;
+    });
+    return pending;
+  }
+  return {
+    async models() {
+      const c = await connection();
+      return {
+        models: [{ id: c.model }],
+        preview: {
+          expiresAt: c.expiresAt,
+          maxCalls: c.maxCalls,
+          maxUnits: c.maxUnits
+        }
+      };
+    },
+    chat: {
+      completions: {
+        async *stream(request, options3 = {}) {
+          const c = await connection();
+          if (request.model !== c.model)
+            throw new ModelGatewayRequestError(
+              400,
+              "Choose the model authorized for this local session."
+            );
+          const response = await optionsFetch(
+            `${c.gatewayBaseUrl}/chat/completions`,
+            {
+              method: "POST",
+              redirect: "error",
+              signal: options3.signal ? AbortSignal.any([options3.signal, AbortSignal.timeout(6e4)]) : AbortSignal.timeout(6e4),
+              headers: {
+                authorization: `Bearer ${c.capability}`,
+                "content-type": "application/json"
+              },
+              body: JSON.stringify({ ...request, stream: true })
+            }
+          );
+          if (!response.ok) {
+            await response.body?.cancel();
+            throw new ModelGatewayRequestError(
+              response.status,
+              "The local model stream was refused. No automatic retry was sent."
+            );
+          }
+          yield* readModelStream(response);
+        },
+        async create(request) {
+          const c = await connection();
+          if (request.model !== c.model)
+            throw new ModelGatewayRequestError(
+              400,
+              "Choose the model authorized for this local session."
+            );
+          const response = await (options2.fetch ?? fetch)(
+            `${c.gatewayBaseUrl}/chat/completions`,
+            {
+              method: "POST",
+              redirect: "error",
+              signal: AbortSignal.timeout(6e4),
+              headers: {
+                authorization: `Bearer ${c.capability}`,
+                "content-type": "application/json"
+              },
+              body: JSON.stringify({ ...request, stream: false })
+            }
+          );
+          if (!response.ok) {
+            await response.body?.cancel();
+            throw new ModelGatewayRequestError(
+              response.status,
+              "The local model request was refused or failed. No automatic retry was sent."
+            );
+          }
+          return response.json();
+        }
+      }
+    }
+  };
+}
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
   ATTR_API_NAME,
@@ -5703,10 +6073,12 @@ var RateLimiter = class {
   auditComplianceAccess,
   auditEnabled,
   auditEventType,
+  bindRuntimeAuth,
   createContext,
   createEmailClient,
   createHmacToken,
   createInstanceGatewayTransport,
+  createLocalModelGatewayClient,
   createModelGatewayClient,
   createPaymentsClient,
   createPreviewModelGatewayClient,
@@ -5756,6 +6128,7 @@ var RateLimiter = class {
   put,
   recordMetric,
   recordRequestAudit,
+  registerDelegatedSurface,
   resetProcessHandlersForTesting,
   signPlatformEvent,
   smsSegments,