@kya-os/agentshield-nextjs 0.2.12 → 0.3.0

package/dist/index.mjs

@@ -1,4 +1,4 @@
-import { loadRulesSync, mapVerificationMethod, createEvaluationContext, evaluatePolicy, ENFORCEMENT_ACTIONS, PolicyConfigSchema, DEFAULT_POLICY, matchPath as matchPath$1, createPolicyFetcher } from '@kya-os/agentshield-shared';
+import { loadRulesSync, shouldEnforce, evaluateEnforcement, createEvaluationContext, evaluatePolicy, ENFORCEMENT_ACTIONS, PolicyConfigSchema, DEFAULT_POLICY, matchPath as matchPath$1, createPolicyFetcher, mapVerificationMethod } from '@kya-os/agentshield-shared';
 export { DEFAULT_POLICY, ENFORCEMENT_ACTIONS, createEvaluationContext, evaluatePolicy } from '@kya-os/agentshield-shared';
 import { NextResponse } from 'next/server';
 import * as ed25519 from '@noble/ed25519';
@@ -232,7 +232,15 @@ var init_edge_detector_with_wasm = __esm({
         }
         const signaturePresent = !!(normalizedHeaders["signature"] || normalizedHeaders["signature-input"]);
         const signatureAgent = normalizedHeaders["signature-agent"];
-        if (signatureAgent?.includes("chatgpt.com")) {
+        const isChatGPT = (() => {
+          try {
+            const url = new URL(signatureAgent?.replace(/^"|"$/g, "") || "");
+            return url.hostname === "chatgpt.com" || url.hostname.endsWith(".chatgpt.com");
+          } catch {
+            return false;
+          }
+        })();
+        if (isChatGPT) {
           confidence = 85;
           reasons.push("signature_agent:chatgpt");
           detectedAgent = { type: "chatgpt", name: "ChatGPT" };
@@ -759,7 +767,15 @@ async function verifyAgentSignature(method, path, headers) {
   }
   let agent;
   let agentKey;
-  if (signatureAgent === '"https://chatgpt.com"' || signatureAgent?.includes("chatgpt.com")) {
+  const isChatGPT = signatureAgent === '"https://chatgpt.com"' || (() => {
+    try {
+      const url = new URL(signatureAgent?.replace(/^"|"$/g, "") || "");
+      return url.hostname === "chatgpt.com" || url.hostname.endsWith(".chatgpt.com");
+    } catch {
+      return false;
+    }
+  })();
+  if (isChatGPT) {
     agent = "ChatGPT";
     agentKey = "chatgpt";
   }
@@ -1056,11 +1072,6 @@ var EdgeAgentDetectorWrapper = class {
     return;
   }
 };
-
-// src/middleware.ts
-init_edge_detector_with_wasm();
-
-// src/session-tracker.ts
 var EdgeSessionTracker = class {
   config;
   constructor(config) {
@@ -1077,7 +1088,7 @@ var EdgeSessionTracker = class {
    */
   async track(_request, response, result) {
     try {
-      if (!this.config.enabled || !result.isAgent) {
+      if (!this.config.enabled || !shouldEnforce(result)) {
         return response;
       }
       const sessionData = {
@@ -1152,9 +1163,7 @@ var EdgeSessionTracker = class {
       for (let i = 0; i < encoded.length; i++) {
         obfuscated[i] = (encoded[i] || 0) ^ key.charCodeAt(i % key.length);
       }
-      return btoa(
-        Array.from(obfuscated, (byte) => String.fromCharCode(byte)).join("")
-      );
+      return btoa(Array.from(obfuscated, (byte) => String.fromCharCode(byte)).join(""));
     } catch (error) {
       return btoa(data);
     }
@@ -1179,9 +1188,9 @@ var EdgeSessionTracker = class {
 var StatelessSessionChecker = class {
   static check(headers) {
     try {
-      const agent = headers["x-agentshield-session-agent"];
-      const confidence = headers["x-agentshield-session-confidence"];
-      const sessionId = headers["x-agentshield-session-id"];
+      const agent = headers["kya-session-agent"];
+      const confidence = headers["kya-session-confidence"];
+      const sessionId = headers["kya-session-id"];
       if (agent && confidence && sessionId) {
         return {
           id: sessionId,
@@ -1211,33 +1220,49 @@ var StatelessSessionChecker = class {
   static setHeaders(response, session) {
     try {
       if (response.setHeader) {
-        response.setHeader("X-AgentShield-Session-Agent", session.agent);
-        response.setHeader(
-          "X-AgentShield-Session-Confidence",
-          session.confidence.toString()
-        );
-        response.setHeader("X-AgentShield-Session-Id", session.id);
+        response.setHeader("KYA-Session-Agent", session.agent);
+        response.setHeader("KYA-Session-Confidence", session.confidence.toString());
+        response.setHeader("KYA-Session-Id", session.id);
       } else if (response.headers && response.headers.set) {
-        response.headers.set("x-agentshield-session-agent", session.agent);
-        response.headers.set(
-          "x-agentshield-session-confidence",
-          session.confidence.toString()
-        );
-        response.headers.set("x-agentshield-session-id", session.id);
+        response.headers.set("kya-session-agent", session.agent);
+        response.headers.set("kya-session-confidence", session.confidence.toString());
+        response.headers.set("kya-session-id", session.id);
       }
     } catch {
     }
   }
 };
 
-// src/middleware.ts
+// src/utils.ts
+function getClientIp(request) {
+  const forwardedFor = request.headers.get("x-forwarded-for");
+  if (forwardedFor) {
+    const ip = forwardedFor.split(",")[0]?.trim();
+    if (ip) return ip;
+  }
+  const realIp = request.headers.get("x-real-ip");
+  if (realIp) return realIp;
+  const cfIp = request.headers.get("cf-connecting-ip");
+  if (cfIp) return cfIp;
+  const clientIp = request.headers.get("x-client-ip");
+  if (clientIp) return clientIp;
+  return void 0;
+}
+function safeHostname(url) {
+  try {
+    return new URL(url).hostname;
+  } catch {
+    return "this site";
+  }
+}
 function createAgentShieldMiddleware(config = {}) {
-  const detector = config.enableWasm ? new EdgeAgentDetectorWrapperWithWasm({ enableWasm: true }) : new EdgeAgentDetectorWrapper(config);
+  let detector = config.enableWasm ? null : new EdgeAgentDetectorWrapper(config);
+  let detectorInitPromise = null;
   const sessionTracker = config.sessionTracking?.enabled || config.enableWasm ? new EdgeSessionTracker({
     enabled: true,
     ...config.sessionTracking
   }) : null;
-  if (config.events) {
+  if (detector && config.events) {
     Object.entries(config.events).forEach(([event, handler]) => {
       if (handler) {
         detector.on(event, handler);
@@ -1258,6 +1283,23 @@ function createAgentShieldMiddleware(config = {}) {
   } = config;
   return async (request) => {
     try {
+      if (!detector) {
+        if (!detectorInitPromise) {
+          detectorInitPromise = (async () => {
+            const { EdgeAgentDetectorWrapperWithWasm: EdgeAgentDetectorWrapperWithWasm2 } = await Promise.resolve().then(() => (init_edge_detector_with_wasm(), edge_detector_with_wasm_exports));
+            detector = new EdgeAgentDetectorWrapperWithWasm2({ enableWasm: true });
+            if (config.events) {
+              Object.entries(config.events).forEach(([event, handler]) => {
+                if (handler) {
+                  detector.on(event, handler);
+                }
+              });
+            }
+          })();
+        }
+        await detectorInitPromise;
+      }
+      const activeDetector = detector;
       const shouldSkip = skipPaths.some((pattern) => {
         if (typeof pattern === "string") {
           return request.nextUrl.pathname.startsWith(pattern);
@@ -1271,11 +1313,11 @@ function createAgentShieldMiddleware(config = {}) {
       const existingSession = sessionTracker ? await sessionTracker.check(request) : null;
       if (existingSession) {
         const response2 = NextResponse.next();
-        response2.headers.set("x-agentshield-detected", "true");
-        response2.headers.set("x-agentshield-agent", existingSession.agent);
-        response2.headers.set("x-agentshield-confidence", existingSession.confidence.toString());
-        response2.headers.set("x-agentshield-session", "continued");
-        response2.headers.set("x-agentshield-session-id", existingSession.id);
+        response2.headers.set("kya-detected", "true");
+        response2.headers.set("kya-agent", existingSession.agent);
+        response2.headers.set("kya-confidence", existingSession.confidence.toString());
+        response2.headers.set("kya-session", "continued");
+        response2.headers.set("kya-session-id", existingSession.id);
         request.agentShield = {
           result: {
             isAgent: true,
@@ -1295,17 +1337,17 @@ function createAgentShieldMiddleware(config = {}) {
         };
         const context2 = {
           userAgent: request.headers.get("user-agent") || "",
-          ipAddress: (request.ip ?? request.headers.get("x-forwarded-for")) || "",
+          ipAddress: getClientIp(request) || "",
           headers: Object.fromEntries(request.headers.entries()),
           url: request.url,
           method: request.method,
           timestamp: /* @__PURE__ */ new Date()
         };
-        detector.emit("agent.session.continued", existingSession, context2);
+        activeDetector.emit("agent.session.continued", existingSession, context2);
         return response2;
       }
       const userAgent = request.headers.get("user-agent");
-      const ipAddress = request.ip ?? request.headers.get("x-forwarded-for");
+      const ipAddress = getClientIp(request);
       const url = new URL(request.url);
       const pathWithQuery = url.pathname + url.search;
       const context = {
@@ -1317,15 +1359,19 @@ function createAgentShieldMiddleware(config = {}) {
         method: request.method,
         timestamp: /* @__PURE__ */ new Date()
       };
-      const result = await detector.analyze(context);
-      if (result.isAgent && result.confidence >= (config.confidenceThreshold ?? 70)) {
+      const result = await activeDetector.analyze(context);
+      const decision = evaluateEnforcement(result, {
+        confidenceThreshold: config.confidenceThreshold,
+        defaultAction: onAgentDetected
+      });
+      if (decision.shouldNotify) {
         if (onDetection) {
           const customResponse = await onDetection(request, result);
           if (customResponse) {
             return customResponse;
           }
         }
-        switch (onAgentDetected) {
+        switch (decision.action) {
           case "block": {
             const response2 = NextResponse.json(
               {
@@ -1341,11 +1387,17 @@ function createAgentShieldMiddleware(config = {}) {
                 response2.headers.set(key, value);
               });
             }
-            detector.emit("agent.blocked", result, context);
+            activeDetector.emit("agent.blocked", result, context);
             return response2;
           }
-          case "redirect":
-            return NextResponse.redirect(new URL(redirectUrl, request.url));
+          case "redirect": {
+            const redirectTarget = new URL(redirectUrl, request.url);
+            const agentName = result.detectedAgent?.name;
+            if (agentName && !redirectTarget.searchParams.has("agent")) {
+              redirectTarget.searchParams.set("agent", agentName.toLowerCase());
+            }
+            return NextResponse.redirect(redirectTarget);
+          }
           case "rewrite":
             return NextResponse.rewrite(new URL(rewriteUrl, request.url));
           case "log":
@@ -1361,9 +1413,7 @@ function createAgentShieldMiddleware(config = {}) {
             break;
           case "allow":
           default:
-            if (result.isAgent && result.confidence >= (config.confidenceThreshold ?? 70)) {
-              detector.emit("agent.allowed", result, context);
-            }
+            activeDetector.emit("agent.allowed", result, context);
             break;
         }
       }
@@ -1372,15 +1422,15 @@ function createAgentShieldMiddleware(config = {}) {
         skipped: false
       };
       let response = NextResponse.next();
-      response.headers.set("x-agentshield-detected", result.isAgent.toString());
-      response.headers.set("x-agentshield-confidence", result.confidence.toString());
+      response.headers.set("kya-detected", result.isAgent.toString());
+      response.headers.set("kya-confidence", result.confidence.toString());
       if (result.detectedAgent?.name) {
-        response.headers.set("x-agentshield-agent", result.detectedAgent.name);
+        response.headers.set("kya-agent", result.detectedAgent.name);
       }
-      if (sessionTracker && result.isAgent && result.confidence >= (config.confidenceThreshold ?? 70)) {
+      if (sessionTracker && decision.shouldNotify) {
         response = await sessionTracker.track(request, response, result);
-        response.headers.set("x-agentshield-session", "new");
-        detector.emit("agent.session.started", result, context);
+        response.headers.set("kya-session", "new");
+        activeDetector.emit("agent.session.started", result, context);
       }
       return response;
     } catch (error) {
@@ -1721,8 +1771,6 @@ async function createStorageAdapter(config) {
   }
   return new MemoryStorageAdapter();
 }
-
-// src/enhanced-middleware.ts
 var SessionManager = class {
   sessionLastActivity = /* @__PURE__ */ new Map();
   generateSessionId(ipAddress, userAgent) {
@@ -1829,7 +1877,7 @@ function createEnhancedAgentShieldMiddleware(config = {}) {
       return NextResponse.next();
     }
     const userAgent = request.headers.get("user-agent");
-    const ipAddress = request.ip ?? request.headers.get("x-forwarded-for");
+    const ipAddress = getClientIp(request);
     const url = new URL(request.url);
     const pathWithQuery = url.pathname + url.search;
     const context = {
@@ -1844,14 +1892,21 @@ function createEnhancedAgentShieldMiddleware(config = {}) {
     const result = await activeDetector.analyze(context);
     let finalConfidence = result.confidence;
     let verificationMethod = result.verificationMethod || "pattern";
-    if (result.isAgent && wasmConfidenceUtils) {
+    if (shouldEnforce(result) && wasmConfidenceUtils) {
       const reasons = result.reasons || [];
       if (wasmConfidenceUtils.shouldIndicateWasmVerification(result.confidence)) {
         finalConfidence = wasmConfidenceUtils.getWasmConfidenceBoost(result.confidence, reasons);
         verificationMethod = wasmConfidenceUtils.getVerificationMethod(finalConfidence, reasons);
       }
     }
-    if (result.isAgent && finalConfidence >= (config.confidenceThreshold ?? 0.7)) {
+    const decision = evaluateEnforcement(
+      { ...result, confidence: finalConfidence },
+      {
+        confidenceThreshold: config.confidenceThreshold,
+        defaultAction: config.onAgentDetected
+      }
+    );
+    if (decision.shouldNotify) {
       if (sessionTrackingEnabled) {
         const storage = await getStorage();
         const sessionId = sessionManager.generateSessionId(
@@ -1915,26 +1970,23 @@ function createEnhancedAgentShieldMiddleware(config = {}) {
       if (config.onDetection) {
         await config.onDetection(result, context);
       }
-      switch (config.onAgentDetected) {
+      switch (decision.action) {
         case "block": {
           const { status = 403, message = "Access denied: AI agent detected" } = config.blockedResponse || {};
           const response2 = NextResponse.json(
             { error: message, detected: true, confidence: finalConfidence },
             { status }
           );
-          response2.headers.set("x-agentshield-detected", "true");
-          response2.headers.set(
-            "x-agentshield-confidence",
-            String(Math.round(finalConfidence * 100))
-          );
-          response2.headers.set("x-agentshield-agent", result.detectedAgent?.name || "Unknown");
-          response2.headers.set("x-agentshield-verification", verificationMethod);
+          response2.headers.set("kya-detected", "true");
+          response2.headers.set("kya-confidence", String(Math.round(finalConfidence * 100)));
+          response2.headers.set("kya-agent", result.detectedAgent?.name || "Unknown");
+          response2.headers.set("kya-verification", verificationMethod);
           return response2;
         }
         case "log": {
           const isInteresting = finalConfidence >= 0.9 || result.detectedAgent?.name?.toLowerCase().includes("chatgpt") || result.detectedAgent?.name?.toLowerCase().includes("perplexity") || verificationMethod === "signature";
           if (isInteresting && process.env.NODE_ENV !== "production") {
-            console.debug(`[AgentShield] \u{1F916} AI Agent detected (${verificationMethod}):`, {
+            console.debug(`[AgentShield] AI Agent detected (${verificationMethod}):`, {
               agent: result.detectedAgent?.name,
               confidence: `${(finalConfidence * 100).toFixed(0)}%`,
               path: pathWithQuery,
@@ -1947,14 +1999,14 @@ function createEnhancedAgentShieldMiddleware(config = {}) {
     }
     const response = NextResponse.next();
     if (result.isAgent) {
-      response.headers.set("x-agentshield-detected", "true");
-      response.headers.set("x-agentshield-confidence", String(Math.round(finalConfidence * 100)));
-      response.headers.set("x-agentshield-agent", result.detectedAgent?.name || "Unknown");
-      response.headers.set("x-agentshield-verification", verificationMethod);
+      response.headers.set("kya-detected", "true");
+      response.headers.set("kya-confidence", String(Math.round(finalConfidence * 100)));
+      response.headers.set("kya-agent", result.detectedAgent?.name || "Unknown");
+      response.headers.set("kya-verification", verificationMethod);
       if (finalConfidence > 0.9) {
-        response.headers.set("x-ai-visitor", "true");
-        response.headers.set("x-ai-confidence", finalConfidence.toString());
-        response.headers.set("x-ai-verification", verificationMethod);
+        response.headers.set("kya-ai-visitor", "true");
+        response.headers.set("kya-ai-confidence", finalConfidence.toString());
+        response.headers.set("kya-ai-verification", verificationMethod);
       }
     }
     return response;
@@ -1963,7 +2015,7 @@ function createEnhancedAgentShieldMiddleware(config = {}) {
 
 // src/api-client.ts
 var DEFAULT_BASE_URL = "https://kya.vouched.id";
-var EDGE_DETECT_URL = "https://detect.kya-os.ai";
+var EDGE_DETECT_URL = "https://detect.checkpoint-gateway.ai";
 var DEFAULT_TIMEOUT = 5e3;
 var AgentShieldClient = class {
   apiKey;
@@ -2153,6 +2205,80 @@ function getAgentShieldClient(config) {
 function resetAgentShieldClient() {
   clientInstance = null;
 }
+var MCP_I_DOCS_URL = "https://docs.knowthat.ai/mcp-i/getting-started";
+var DEFAULT_CONNECT_PATH = "/connect";
+function buildAgentInstructionResponse(request, decision, redirectUrl) {
+  const resolved = resolveUrl(redirectUrl ?? DEFAULT_CONNECT_PATH, request.url);
+  const agentName = decision.agentName || decision.agentType || "unknown";
+  if (!resolved.searchParams.has("agent")) {
+    resolved.searchParams.set("agent", agentName.toLowerCase());
+  }
+  const authUrl = resolved.toString();
+  const hostname = safeHostname(request.url);
+  const body = {
+    // Markdown-formatted so clients that render markdown (Claude Desktop,
+    // ChatGPT web) surface the URL as a clickable link. Tone mirrors the
+    // gateway response so messaging stays consistent across platforms.
+    message: `I can't access ${hostname} yet \u2014 this site checks AI assistants at the front door.
+
+**To give me access, open this link:**
+[Connect securely to ${hostname}](${authUrl})
+
+It only takes a moment and you won't need to do it again. Once you're done, ask me to try again and I'll connect through the verified channel automatically.`,
+    user_action_required: {
+      action: `Connect securely to ${hostname}`,
+      url: authUrl,
+      reason: `${hostname} checks AI assistants before they connect. Open the link to give your assistant a verified key.`
+    },
+    mcp_i: {
+      version: "1.0",
+      action: "authenticate",
+      authorization_url: authUrl,
+      flow: {
+        type: "oauth2_delegation",
+        steps: [
+          "1. Direct your user to the authorization_url",
+          "2. User reviews requested scopes and grants consent",
+          "3. Receive delegation credential (JWT)",
+          "4. Include credential in KYA-Delegation header",
+          "5. Retry this request with the proof"
+        ]
+      },
+      retry_instructions: {
+        header: "KYA-Delegation",
+        format: "JWT delegation credential from authorization flow"
+      },
+      documentation: MCP_I_DOCS_URL
+    },
+    error: "mcp_authentication_required",
+    code: "AGENT_REQUIRES_DELEGATION",
+    detection: {
+      agent_type: decision.agentType || "ai_agent",
+      agent_name: decision.agentName || "Unknown Agent",
+      confidence: decision.confidence
+    }
+  };
+  const response = NextResponse.json(body, { status: 401 });
+  response.headers.set("WWW-Authenticate", `KYA realm="api", authorization_uri="${authUrl}"`);
+  response.headers.set(
+    "Link",
+    `<${authUrl}>; rel="kya-authorize", <${MCP_I_DOCS_URL}>; rel="help"`
+  );
+  response.headers.set("KYA-Auth-Required", "true");
+  response.headers.set("KYA-Auth-Url", authUrl);
+  response.headers.set("KYA-Action", "instruct");
+  response.headers.set("KYA-Detected-Agent", agentName);
+  response.headers.set("KYA-Confidence", decision.confidence.toString());
+  response.headers.set("Cache-Control", "no-store");
+  return response;
+}
+function resolveUrl(target, baseUrl2) {
+  try {
+    return new URL(target, baseUrl2);
+  } catch {
+    return new URL(DEFAULT_CONNECT_PATH, baseUrl2);
+  }
+}
 
 // src/api-middleware.ts
 function matchPath(path, pattern) {
@@ -2173,35 +2299,52 @@ function shouldIncludePath(path, includePaths) {
   if (!includePaths || includePaths.length === 0) return true;
   return includePaths.some((pattern) => matchPath(path, pattern));
 }
-function buildBlockedResponse(decision, config) {
+function buildBlockedResponse(request, decision, config) {
   const status = config.blockedResponse?.status ?? 403;
-  const redirectUrl = config.redirectUrl || decision.redirectUrl;
-  const baseMessage = config.blockedResponse?.message ?? decision.message ?? "Access denied";
-  const errorMessage = redirectUrl ? `${baseMessage}. Please go to ${redirectUrl}` : baseMessage;
-  const message = config.blockedResponse?.message ?? decision.message ?? (redirectUrl ? `AI agents are not permitted on this resource. Please go to ${redirectUrl} for more information.` : "AI agents are not permitted on this resource.");
-  const responseBody = {
-    error: errorMessage,
+  const message = config.blockedResponse?.message ?? decision.message ?? "Access denied";
+  const recoveryUrl = resolveRecoveryUrl(request, config.redirectUrl || decision.redirectUrl);
+  const body = {
+    error: message,
     code: "AGENT_BLOCKED",
     reason: decision.reason,
-    agentType: decision.agentType,
-    message
+    agentType: decision.agentType
   };
-  if (redirectUrl) {
-    responseBody.redirectUrl = redirectUrl;
+  if (recoveryUrl) {
+    const hostname = safeHostname(request.url);
+    body.user_action_required = {
+      action: `Connect securely to ${hostname}`,
+      url: recoveryUrl,
+      reason: `${hostname} blocks unverified AI assistants. Open the link to give your assistant a verified key and try again.`
+    };
+    body.message = `I can't access ${hostname} \u2014 this site blocks unverified AI assistants.
+
+**To give me access, open this link:**
+[Connect securely to ${hostname}](${recoveryUrl})
+
+Once you're done, ask me to try again.`;
   }
-  const response = NextResponse.json(responseBody, { status });
+  const response = NextResponse.json(body, { status });
   if (config.blockedResponse?.headers) {
     for (const [key, value] of Object.entries(config.blockedResponse.headers)) {
       response.headers.set(key, value);
     }
   }
-  response.headers.set("X-AgentShield-Action", decision.action);
-  response.headers.set("X-AgentShield-Reason", decision.reason);
-  if (redirectUrl) {
-    response.headers.set("X-AgentShield-Redirect", redirectUrl);
+  if (recoveryUrl) {
+    response.headers.set("Link", `<${recoveryUrl}>; rel="kya-authorize"`);
+    response.headers.set("KYA-Auth-Url", recoveryUrl);
   }
+  response.headers.set("KYA-Action", decision.action);
+  response.headers.set("KYA-Reason", decision.reason);
   return response;
 }
+function resolveRecoveryUrl(request, target) {
+  if (!target) return void 0;
+  try {
+    return new URL(target, request.url).toString();
+  } catch {
+    return void 0;
+  }
+}
 function buildRedirectResponse(request, decision, config) {
   const redirectUrl = config.redirectUrl || decision.redirectUrl || "/blocked";
   const url = new URL(redirectUrl, request.url);
@@ -2246,7 +2389,7 @@ function withAgentShield(config = {}) {
     try {
       const client2 = getClient();
       const userAgent = request.headers.get("user-agent") || void 0;
-      const ipAddress = request.ip || request.headers.get("x-forwarded-for")?.split(",")[0]?.trim() || request.headers.get("x-real-ip") || void 0;
+      const ipAddress = getClientIp(request);
       const result = await client2.enforce({
         headers: Object.fromEntries(request.headers.entries()),
         userAgent,
@@ -2297,6 +2440,7 @@ function withAgentShield(config = {}) {
       if (decision.isAgent && config.onAgentDetected) {
         await config.onAgentDetected(request, decision);
       }
+      const redirectMode = config.redirectMode ?? "instruct";
       switch (decision.action) {
         case "block": {
           if (config.customBlockedResponse) {
@@ -2305,10 +2449,15 @@ function withAgentShield(config = {}) {
           if (config.onBlock === "redirect") {
             return buildRedirectResponse(request, decision, config);
           }
-          return buildBlockedResponse(decision, config);
+          return buildBlockedResponse(request, decision, config);
         }
-        case "redirect": {
-          return buildRedirectResponse(request, decision, config);
+        case "redirect":
+        case "instruct": {
+          if (redirectMode === "http" && decision.action === "redirect") {
+            return buildRedirectResponse(request, decision, config);
+          }
+          const targetUrl = config.redirectUrl || decision.redirectUrl;
+          return buildAgentInstructionResponse(request, decision, targetUrl);
         }
         case "challenge": {
           return buildRedirectResponse(request, decision, config);
@@ -2318,10 +2467,10 @@ function withAgentShield(config = {}) {
         default: {
           const response = NextResponse.next();
           if (decision.isAgent) {
-            response.headers.set("X-AgentShield-Detected", "true");
-            response.headers.set("X-AgentShield-Confidence", decision.confidence.toString());
+            response.headers.set("KYA-Detected", "true");
+            response.headers.set("KYA-Confidence", decision.confidence.toString());
             if (decision.agentName) {
-              response.headers.set("X-AgentShield-Agent", decision.agentName);
+              response.headers.set("KYA-Agent", decision.agentName);
             }
           }
           return response;
@@ -2379,24 +2528,28 @@ function buildBlockedResponse2(decision, config) {
       response.headers.set(key, value);
     }
   }
-  response.headers.set("X-AgentShield-Action", decision.action);
-  response.headers.set("X-AgentShield-Reason", decision.reason);
-  response.headers.set("X-AgentShield-MatchType", decision.matchType);
+  response.headers.set("KYA-Action", decision.action);
+  response.headers.set("KYA-Reason", decision.reason);
+  response.headers.set("KYA-Match-Type", decision.matchType);
   return response;
 }
-function buildRedirectResponse2(request, decision, config) {
+function buildRedirectResponse2(request, decision, config, detection) {
   const redirectUrl = decision.redirectUrl || config.redirectUrl || "/blocked";
   const url = new URL(redirectUrl, request.url);
   url.searchParams.set("reason", decision.reason);
   if (decision.ruleId) {
     url.searchParams.set("ruleId", decision.ruleId);
   }
+  const agentName = detection?.detectedAgent?.name;
+  if (agentName && !url.searchParams.has("agent")) {
+    url.searchParams.set("agent", agentName.toLowerCase());
+  }
   return NextResponse.redirect(url);
 }
-function buildChallengeResponse(request, decision, config) {
-  return buildRedirectResponse2(request, decision, config);
+function buildChallengeResponse(request, decision, config, detection) {
+  return buildRedirectResponse2(request, decision, config, detection);
 }
-async function handlePolicyDecision(request, decision, config) {
+async function handlePolicyDecision(request, decision, config, detection) {
   switch (decision.action) {
     case ENFORCEMENT_ACTIONS.BLOCK:
       if (config.customBlockedResponse) {
@@ -2404,9 +2557,9 @@ async function handlePolicyDecision(request, decision, config) {
       }
       return buildBlockedResponse2(decision, config);
     case ENFORCEMENT_ACTIONS.REDIRECT:
-      return buildRedirectResponse2(request, decision, config);
+      return buildRedirectResponse2(request, decision, config, detection);
     case ENFORCEMENT_ACTIONS.CHALLENGE:
-      return buildChallengeResponse(request, decision, config);
+      return buildChallengeResponse(request, decision, config, detection);
     case ENFORCEMENT_ACTIONS.LOG:
       console.log("[AgentShield] Policy decision (log):", {
         path: request.nextUrl.pathname,
@@ -2480,7 +2633,7 @@ async function applyPolicy(request, detection, config) {
     if (config.onPolicyDecision) {
       await config.onPolicyDecision(request, decision, context);
     }
-    return await handlePolicyDecision(request, decision, config);
+    return await handlePolicyDecision(request, decision, config, detection);
   } catch (error) {
     if (config.debug) {
       console.error("[AgentShield] Policy evaluation error:", error);