agentid-sdk 0.1.24 → 0.1.26

package/dist/index.js

@@ -32,6 +32,7 @@ var index_exports = {};
 __export(index_exports, {
   AgentID: () => AgentID,
   AgentIDTransparencyBadge: () => AgentIDTransparencyBadge,
+  DependencyError: () => DependencyError,
   InjectionScanner: () => InjectionScanner,
   OpenAIAdapter: () => OpenAIAdapter,
   PIIManager: () => PIIManager,
@@ -85,7 +86,7 @@ var OpenAIAdapter = class {
 
 // src/sdk-version.ts
 var FALLBACK_SDK_VERSION = "js-0.0.0-dev";
-var AGENTID_SDK_VERSION_HEADER = "js-0.1.24".trim().length > 0 ? "js-0.1.24" : FALLBACK_SDK_VERSION;
+var AGENTID_SDK_VERSION_HEADER = "js-0.1.26".trim().length > 0 ? "js-0.1.26" : FALLBACK_SDK_VERSION;
 
 // src/pii-national-identifiers.ts
 var MAX_CANDIDATES_PER_RULE = 256;
@@ -1204,6 +1205,7 @@ var DEFAULT_FAIL_OPEN_CONFIG = {
   block_on_heuristic: false,
   inject_transparency_metadata: false,
   block_pii_leakage: false,
+  enable_sdk_pii_masking: false,
   block_db_access: false,
   block_code_execution: false,
   block_toxicity: false
@@ -1306,8 +1308,8 @@ var LocalSecurityEnforcer = class {
 
 // src/capability-config.ts
 var CONFIG_TTL_MS = 5 * 60 * 1e3;
-var CONFIG_TIMEOUT_MS = 8e3;
-var CONFIG_RETRY_DELAY_MS = 1e3;
+var CONFIG_TIMEOUT_MS = 1500;
+var CONFIG_RETRY_DELAY_MS = 150;
 var MAX_CAPABILITY_CACHE_ENTRIES = 500;
 var CapabilityConfigFetchError = class extends Error {
   constructor(message, params) {
@@ -1391,6 +1393,11 @@ function normalizeCapabilityConfig(payload) {
       false
     ),
     block_pii_leakage: readBooleanField(body, "block_pii_leakage", "block_pii"),
+    enable_sdk_pii_masking: readOptionalBooleanField(
+      body,
+      "enable_sdk_pii_masking",
+      false
+    ),
     block_db_access: readBooleanField(body, "block_db_access", "block_db"),
     block_code_execution: readBooleanField(
       body,
@@ -1554,6 +1561,79 @@ async function ensureCapabilityConfig(params) {
   return pending;
 }
 
+// src/context-intent.ts
+var EDUCATIONAL_MARKERS = [
+  "explain",
+  "analysis",
+  "analyze",
+  "analyse",
+  "review",
+  "summarize",
+  "summarise",
+  "summary",
+  "plain-language explanation",
+  "red flags",
+  "security workshop",
+  "training",
+  "lesson",
+  "quoted attack",
+  "quoted example",
+  "attack example",
+  "security event",
+  "security log",
+  "audit log",
+  "incident report",
+  "trace timeline"
+];
+var WARNING_MARKERS = [
+  "dangerous",
+  "risky",
+  "risk",
+  "warning",
+  "warn",
+  "malicious",
+  "security indicator",
+  "red flags"
+];
+var NON_EXECUTION_MARKERS = [
+  "do not execute",
+  "do not run",
+  "do not return commands",
+  "do not output commands",
+  "do not provide executable steps",
+  "for explanation only",
+  "non-executable"
+];
+function normalizeIntentInput(input) {
+  return input.toLowerCase().normalize("NFD").replace(/[\u0300-\u036f]/g, "").replace(/\s+/g, " ").trim();
+}
+function hasAnyMarker(input, markers) {
+  return markers.some((marker) => input.includes(marker));
+}
+function classifyInjectionContextIntent(input) {
+  const normalized = normalizeIntentInput(input ?? "");
+  if (!normalized) {
+    return {
+      educational: false,
+      quotedExample: false,
+      warningOnly: false,
+      nonExecutableConstraint: false,
+      promptInjectionExempt: false
+    };
+  }
+  const educational = hasAnyMarker(normalized, EDUCATIONAL_MARKERS);
+  const warningOnly = hasAnyMarker(normalized, WARNING_MARKERS);
+  const nonExecutableConstraint = hasAnyMarker(normalized, NON_EXECUTION_MARKERS);
+  const quotedExample = /["'`]/.test(input) || normalized.includes("quoted") || normalized.includes("quote") || normalized.includes("phrase") || normalized.includes("attack example");
+  return {
+    educational,
+    quotedExample,
+    warningOnly,
+    nonExecutableConstraint,
+    promptInjectionExempt: educational && (quotedExample || warningOnly || nonExecutableConstraint || normalized.includes("prompt injection indicator") || normalized.includes("jailbreak prompt"))
+  };
+}
+
 // src/security.ts
 var MAX_ANALYSIS_WINDOW = 8192;
 var WINDOW_SLICE_SIZE = 4e3;
@@ -1561,6 +1641,7 @@ var WORD_BOUNDARY_SCAN = 120;
 var AI_TIMEOUT_MS = 2e3;
 var TELEMETRY_SNIPPET_LIMIT = 4e3;
 var AI_OPENAI_MODEL = "gpt-4o-mini";
+var UUID_RE = /^[0-9a-f]{8}-[0-9a-f]{4}-[1-5][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/i;
 var EN_STOPWORDS = /* @__PURE__ */ new Set([
   "the",
   "and",
@@ -1608,6 +1689,25 @@ var piiSingleton = null;
 function normalizeBaseUrl2(baseUrl) {
   return (baseUrl || "").replace(/\/+$/, "");
 }
+function createPseudoUuidV4() {
+  return "xxxxxxxx-xxxx-4xxx-yxxx-xxxxxxxxxxxx".replace(/[xy]/g, (char) => {
+    const random = Math.floor(Math.random() * 16);
+    const nibble = char === "x" ? random : random & 3 | 8;
+    return nibble.toString(16);
+  });
+}
+function isUuidLike(value) {
+  return typeof value === "string" && UUID_RE.test(value);
+}
+function createEventId(seed) {
+  if (isUuidLike(seed)) {
+    return seed;
+  }
+  if (typeof globalThis.crypto?.randomUUID === "function") {
+    return globalThis.crypto.randomUUID();
+  }
+  return createPseudoUuidV4();
+}
 function getSharedPIIManager() {
   if (!piiSingleton) {
     piiSingleton = new PIIManager();
@@ -1696,6 +1796,10 @@ function findRegexMatch(prompt) {
   if (!prompt) {
     return null;
   }
+  const contextIntent = classifyInjectionContextIntent(prompt);
+  if (contextIntent.promptInjectionExempt) {
+    return null;
+  }
   const normalizedPrompt = normalizeForHeuristics(prompt);
   for (const rule of HEURISTIC_RULES) {
     try {
@@ -1821,13 +1925,16 @@ async function reportSecurityEvent(options) {
   const snippet = truncateSnippet(options.snippet);
   const snippetHash = snippet ? await sha256Hex(snippet) : "";
   const inputValue = options.storePii ? snippet : snippetHash;
+  const eventId = createEventId(options.eventId ?? options.clientEventId);
   const metadata = {
     source: options.source,
     detector: options.detector,
     trigger_rule: options.triggerRule,
     language: options.language,
     ai_scan_status: options.aiStatus ?? null,
-    reason: options.reason ?? null
+    reason: options.reason ?? null,
+    client_event_id: eventId,
+    ...options.telemetryMetadata ?? {}
   };
   if (options.storePii) {
     metadata.snippet = snippet;
@@ -1835,11 +1942,14 @@ async function reportSecurityEvent(options) {
     metadata.snippet_hash = snippetHash;
   }
   const payload = {
+    event_id: eventId,
+    system_id: options.systemId,
     input: inputValue,
     output: "",
     model: "agentid.local_injection_scanner",
     event_type: options.outcome === "blocked" ? "security_block" : "security_alert",
     severity: options.outcome === "blocked" ? "error" : "warning",
+    timestamp: (/* @__PURE__ */ new Date()).toISOString(),
     metadata
   };
   void fetch(`${normalizeBaseUrl2(options.baseUrl)}/ingest`, {
@@ -1869,7 +1979,11 @@ var InjectionScanner = class _InjectionScanner {
       aiScanEnabled: options?.aiScanEnabled,
       storePii: options?.storePii,
       piiManager: options?.piiManager,
-      source: options?.source
+      source: options?.source,
+      systemId: options?.systemId,
+      eventId: options?.eventId,
+      clientEventId: options?.clientEventId,
+      telemetryMetadata: options?.telemetryMetadata
     });
   }
   async scan(params) {
@@ -1881,6 +1995,11 @@ var InjectionScanner = class _InjectionScanner {
     const storePii = params.storePii === true;
     const aiScanEnabled = params.aiScanEnabled !== false;
     const language = detectLanguageTag(prompt);
+    const scanStartedAt = Date.now();
+    const buildTelemetryMetadata = () => ({
+      ...params.telemetryMetadata ?? {},
+      sdk_local_scan_ms: Math.max(0, Date.now() - scanStartedAt)
+    });
     const regexMatch = findRegexMatch(prompt);
     if (regexMatch) {
       await reportSecurityEvent({
@@ -1892,7 +2011,11 @@ var InjectionScanner = class _InjectionScanner {
         triggerRule: regexMatch.rule,
         snippet: regexMatch.snippet,
         storePii,
-        language
+        language,
+        systemId: params.systemId,
+        eventId: params.eventId,
+        clientEventId: params.clientEventId,
+        telemetryMetadata: buildTelemetryMetadata()
       });
       throw new Error(`AgentID: Prompt injection blocked (${regexMatch.rule})`);
     }
@@ -1913,7 +2036,11 @@ var InjectionScanner = class _InjectionScanner {
         storePii,
         language,
         aiStatus: "skipped",
-        reason: "ai_scan_disabled_for_high_risk_language"
+        reason: "ai_scan_disabled_for_high_risk_language",
+        systemId: params.systemId,
+        eventId: params.eventId,
+        clientEventId: params.clientEventId,
+        telemetryMetadata: buildTelemetryMetadata()
       });
       return;
     }
@@ -1932,7 +2059,11 @@ var InjectionScanner = class _InjectionScanner {
         storePii,
         language,
         aiStatus: aiResult.status,
-        reason: aiResult.reason
+        reason: aiResult.reason,
+        systemId: params.systemId,
+        eventId: params.eventId,
+        clientEventId: params.clientEventId,
+        telemetryMetadata: buildTelemetryMetadata()
       });
       return;
     }
@@ -1948,7 +2079,11 @@ var InjectionScanner = class _InjectionScanner {
         storePii,
         language,
         aiStatus: aiResult.status,
-        reason: aiResult.reason
+        reason: aiResult.reason,
+        systemId: params.systemId,
+        eventId: params.eventId,
+        clientEventId: params.clientEventId,
+        telemetryMetadata: buildTelemetryMetadata()
       });
       throw new Error(`AgentID: Prompt injection blocked (${aiResult.reason})`);
     }
@@ -2047,6 +2182,19 @@ function normalizeIngestTimeoutMs(value) {
   }
   return rounded;
 }
+function setFiniteDurationMetadata(metadata, key, value) {
+  if (typeof value === "number" && Number.isFinite(value)) {
+    metadata[key] = Math.max(0, Math.trunc(value));
+  }
+}
+function buildSdkTimingMetadata(params) {
+  const metadata = {};
+  setFiniteDurationMetadata(metadata, "sdk_config_fetch_ms", params.sdkConfigFetchMs);
+  setFiniteDurationMetadata(metadata, "sdk_local_scan_ms", params.sdkLocalScanMs);
+  setFiniteDurationMetadata(metadata, "sdk_guard_ms", params.sdkGuardMs);
+  setFiniteDurationMetadata(metadata, "sdk_ingest_ms", params.sdkIngestMs);
+  return metadata;
+}
 function resolveConfiguredApiKey(value) {
   const explicit = typeof value === "string" ? value.trim() : "";
   const fromEnv = globalThis.process?.env?.AGENTID_API_KEY ?? "";
@@ -2060,13 +2208,32 @@ function isInfrastructureGuardReason(reason) {
   if (!reason) return false;
   return reason === "system_failure" || reason === "system_failure_db_unavailable" || reason === "logging_failed" || reason === "server_error" || reason === "guard_unreachable" || reason === "api_key_pepper_missing" || reason === "encryption_key_missing";
 }
-function isUuidLike(value) {
+function isGuardFailureEligibleForLocalFallback(reason) {
+  return reason === "network_error_strict_mode" || reason === "server_error" || isInfrastructureGuardReason(reason);
+}
+function isFailCloseIngestReason(reason) {
+  if (!reason) return false;
+  return reason === "system_failure" || reason === "system_failure_db_unavailable" || reason === "server_error" || reason === "redis_rate_limit_unavailable" || reason === "redis_quota_unavailable" || reason === "redis_token_quota_unavailable";
+}
+function shouldEscalateIngestFailure(params) {
+  if (!params.strictMode) {
+    return false;
+  }
+  if (params.status === null) {
+    return true;
+  }
+  if (params.status >= 500) {
+    return true;
+  }
+  return isFailCloseIngestReason(params.reason);
+}
+function isUuidLike2(value) {
   if (!value) return false;
   return /^[0-9a-f]{8}-[0-9a-f]{4}-[1-5][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/i.test(
     value
   );
 }
-function createPseudoUuidV4() {
+function createPseudoUuidV42() {
   return "xxxxxxxx-xxxx-4xxx-yxxx-xxxxxxxxxxxx".replace(/[xy]/g, (token) => {
     const rand = Math.floor(Math.random() * 16);
     const value = token === "x" ? rand : rand & 3 | 8;
@@ -2077,19 +2244,28 @@ function sanitizeIngestText(value) {
   const text = typeof value === "string" ? value : String(value ?? "");
   return text.slice(0, MAX_INGEST_TEXT_CHARS);
 }
-function createEventId(seed) {
-  if (isUuidLike(seed)) return seed;
+function normalizeExpectedLanguages(value) {
+  if (!Array.isArray(value)) {
+    return void 0;
+  }
+  const normalized = [...new Set(
+    value.map((entry) => typeof entry === "string" ? entry.trim() : "").filter((entry) => entry.length > 0)
+  )];
+  return normalized.length > 0 ? normalized : void 0;
+}
+function createEventId2(seed) {
+  if (isUuidLike2(seed)) return seed;
   if (typeof globalThis.crypto?.randomUUID === "function") {
     return globalThis.crypto.randomUUID();
   }
-  return createPseudoUuidV4();
+  return createPseudoUuidV42();
 }
 function createCorrelationId(seed) {
-  if (isUuidLike(seed)) return seed;
+  if (isUuidLike2(seed)) return seed;
   if (typeof globalThis.crypto?.randomUUID === "function") {
     return globalThis.crypto.randomUUID();
   }
-  return createPseudoUuidV4();
+  return createPseudoUuidV42();
 }
 async function waitForRetry(attemptIndex) {
   const delay = GUARD_RETRY_DELAYS_MS[attemptIndex];
@@ -2226,28 +2402,60 @@ var SecurityBlockError = class extends Error {
     this.reason = reason;
   }
 };
+var DependencyError = class extends Error {
+  constructor(params) {
+    const statusLabel = typeof params.status === "number" ? String(params.status) : "network";
+    super(`AgentID dependency failure (${params.dependency}): ${params.reason} [${statusLabel}]`);
+    this.name = "DependencyError";
+    this.dependency = params.dependency;
+    this.reason = params.reason;
+    this.status = params.status;
+  }
+};
 var AgentID = class {
   constructor(config = {}) {
     this.injectionScanner = getInjectionScanner();
     this.recentGuardVerdicts = /* @__PURE__ */ new Map();
     this.apiKey = resolveConfiguredApiKey(config.apiKey);
     this.baseUrl = normalizeBaseUrl3(config.baseUrl ?? "https://app.getagentid.com/api/v1");
-    this.piiMasking = Boolean(config.piiMasking);
+    this.configuredPiiMasking = typeof config.piiMasking === "boolean" ? config.piiMasking : null;
     this.checkInjection = config.checkInjection !== false;
+    this.clientFastFail = config.clientFastFail === true || config.client_fast_fail === true;
     this.aiScanEnabled = config.aiScanEnabled !== false;
     this.storePii = config.storePii === true;
     this.strictMode = config.strictMode === true;
+    if (typeof config.failureMode !== "undefined" && config.failureMode !== "fail_open" && config.failureMode !== "fail_close") {
+      throw new Error("AgentID invalid failureMode. Use 'fail_open' or 'fail_close'.");
+    }
+    if (this.strictMode && config.failureMode === "fail_open") {
+      throw new Error("AgentID strictMode=true conflicts with failureMode='fail_open'.");
+    }
+    this.configuredFailureMode = this.strictMode ? "fail_close" : config.failureMode ?? null;
     this.guardTimeoutMs = normalizeGuardTimeoutMs(config.guardTimeoutMs);
     this.ingestTimeoutMs = normalizeIngestTimeoutMs(config.ingestTimeoutMs);
     this.pii = new PIIManager();
     this.localEnforcer = new LocalSecurityEnforcer(this.pii);
     void this.getCapabilityConfig();
   }
-  buildClientCapabilities(framework = "js_sdk", hasFeedbackHandler = false) {
+  get piiMasking() {
+    return this.configuredPiiMasking ?? void 0;
+  }
+  resolveEffectivePiiMasking(config) {
+    if (this.configuredPiiMasking !== null) {
+      return this.configuredPiiMasking;
+    }
+    return config?.enable_sdk_pii_masking === true;
+  }
+  getEffectivePiiMasking(options) {
+    return this.resolveEffectivePiiMasking(this.getCachedCapabilityConfig(options));
+  }
+  buildClientCapabilities(framework = "js_sdk", hasFeedbackHandler = false, capabilityConfig) {
     return {
       capabilities: {
         has_feedback_handler: hasFeedbackHandler,
-        pii_masking_enabled: this.piiMasking,
+        pii_masking_enabled: this.resolveEffectivePiiMasking(
+          capabilityConfig ?? this.getCachedCapabilityConfig()
+        ),
         framework
       }
     };
@@ -2261,17 +2469,17 @@ var AgentID = class {
   }
   resolveClientEventId(requestBody) {
     const directClientEventId = requestBody.client_event_id;
-    if (typeof directClientEventId === "string" && isUuidLike(directClientEventId)) {
+    if (typeof directClientEventId === "string" && isUuidLike2(directClientEventId)) {
       return directClientEventId;
     }
     const metadata = requestBody.metadata;
     if (metadata && typeof metadata === "object" && !Array.isArray(metadata)) {
       const metadataClientEventId = metadata.client_event_id;
-      if (typeof metadataClientEventId === "string" && isUuidLike(metadataClientEventId)) {
+      if (typeof metadataClientEventId === "string" && isUuidLike2(metadataClientEventId)) {
         return metadataClientEventId;
       }
     }
-    return createEventId();
+    return createEventId2();
   }
   buildGuardCacheKey(params) {
     if (!params.system_id || !params.input) {
@@ -2315,6 +2523,14 @@ var AgentID = class {
       force
     });
   }
+  async getCapabilityConfigWithTelemetry(force = false, options) {
+    const configStartedAt = Date.now();
+    const capabilityConfig = await this.getCapabilityConfig(force, options);
+    return {
+      capabilityConfig,
+      sdkConfigFetchMs: Math.max(0, Date.now() - configStartedAt)
+    };
+  }
   getCachedCapabilityConfig(options) {
     const effectiveApiKey = this.resolveApiKey(options?.apiKey);
     return getCachedCapabilityConfig({
@@ -2323,12 +2539,32 @@ var AgentID = class {
     });
   }
   async resolveEffectiveStrictMode(options) {
-    if (this.strictMode) {
+    if (this.strictMode || this.configuredFailureMode === "fail_close") {
       return true;
     }
+    if (this.configuredFailureMode === "fail_open") {
+      return false;
+    }
     const config = await this.getCapabilityConfig(false, options);
     return config.strict_security_mode || config.failure_mode === "fail_close";
   }
+  maybeRaiseStrictIngestDependencyError(params) {
+    if (params.result.ok) {
+      return;
+    }
+    if (!shouldEscalateIngestFailure({
+      strictMode: params.strictMode,
+      status: params.result.status,
+      reason: params.result.reason
+    })) {
+      return;
+    }
+    throw new DependencyError({
+      dependency: "ingest",
+      reason: params.result.reason ?? "ingest_failed",
+      status: params.result.status
+    });
+  }
   shouldRunLocalInjectionScan(config) {
     if (!this.checkInjection) {
       return false;
@@ -2338,37 +2574,45 @@ var AgentID = class {
     }
     return config.block_on_heuristic;
   }
-  async prepareInputForDispatch(params, options) {
-    const effectiveApiKey = this.resolveApiKey(options?.apiKey);
-    const capabilityConfig = await this.getCapabilityConfig(false, options);
-    if (!params.skipInjectionScan && params.input && this.shouldRunLocalInjectionScan(capabilityConfig)) {
+  async applyLocalPolicyChecks(params) {
+    const localScanStartedAt = Date.now();
+    if (params.runPromptInjectionCheck && params.input && this.shouldRunLocalInjectionScan(params.capabilityConfig)) {
       await this.injectionScanner.scan({
         prompt: params.input,
-        apiKey: effectiveApiKey,
+        apiKey: params.apiKey,
         baseUrl: this.baseUrl,
         aiScanEnabled: this.aiScanEnabled,
         storePii: this.storePii,
         piiManager: this.pii,
-        source: "js_sdk"
+        source: "js_sdk",
+        systemId: params.systemId,
+        eventId: params.clientEventId,
+        clientEventId: params.clientEventId,
+        telemetryMetadata: buildSdkTimingMetadata({
+          sdkConfigFetchMs: params.sdkConfigFetchMs
+        })
       });
     }
     try {
       const enforced = this.localEnforcer.enforce({
         input: params.input,
         stream: params.stream,
-        config: capabilityConfig
+        config: params.capabilityConfig
       });
+      const sdkLocalScanMs = Math.max(0, Date.now() - localScanStartedAt);
       for (const event of enforced.events) {
         this.logSecurityPolicyViolation({
           systemId: params.systemId,
           violationType: event.violationType,
           actionTaken: event.actionTaken,
-          apiKey: effectiveApiKey
+          apiKey: params.apiKey,
+          sdkConfigFetchMs: params.sdkConfigFetchMs,
+          sdkLocalScanMs
         });
       }
       return {
         sanitizedInput: enforced.sanitizedInput,
-        capabilityConfig
+        sdkLocalScanMs
       };
     } catch (error) {
       if (error instanceof SecurityPolicyViolationError) {
@@ -2376,17 +2620,76 @@ var AgentID = class {
           systemId: params.systemId,
           violationType: error.violationType,
           actionTaken: error.actionTaken,
-          apiKey: effectiveApiKey
+          apiKey: params.apiKey,
+          sdkConfigFetchMs: params.sdkConfigFetchMs,
+          sdkLocalScanMs: Math.max(0, Date.now() - localScanStartedAt)
         });
       }
       throw error;
     }
   }
+  async prepareInputForDispatch(params, options) {
+    const effectiveApiKey = this.resolveApiKey(options?.apiKey);
+    const { capabilityConfig, sdkConfigFetchMs } = await this.getCapabilityConfigWithTelemetry(
+      false,
+      options
+    );
+    if (!this.clientFastFail) {
+      return {
+        sanitizedInput: params.input,
+        capabilityConfig,
+        sdkConfigFetchMs,
+        sdkLocalScanMs: 0
+      };
+    }
+    const enforced = await this.applyLocalPolicyChecks({
+      input: params.input,
+      systemId: params.systemId,
+      stream: params.stream,
+      capabilityConfig,
+      apiKey: effectiveApiKey,
+      clientEventId: params.clientEventId,
+      sdkConfigFetchMs,
+      runPromptInjectionCheck: !params.skipInjectionScan
+    });
+    return {
+      sanitizedInput: enforced.sanitizedInput,
+      capabilityConfig,
+      sdkConfigFetchMs,
+      sdkLocalScanMs: enforced.sdkLocalScanMs
+    };
+  }
+  async applyLocalFallbackForGuardFailure(params, options) {
+    const effectiveApiKey = this.resolveApiKey(options?.apiKey);
+    const resolvedConfig = params.capabilityConfig && typeof params.sdkConfigFetchMs === "number" ? {
+      capabilityConfig: params.capabilityConfig,
+      sdkConfigFetchMs: params.sdkConfigFetchMs
+    } : await this.getCapabilityConfigWithTelemetry(false, options);
+    const enforced = await this.applyLocalPolicyChecks({
+      input: params.input,
+      systemId: params.systemId,
+      stream: params.stream,
+      capabilityConfig: resolvedConfig.capabilityConfig,
+      apiKey: effectiveApiKey,
+      clientEventId: params.clientEventId,
+      sdkConfigFetchMs: resolvedConfig.sdkConfigFetchMs,
+      runPromptInjectionCheck: true
+    });
+    return {
+      sanitizedInput: enforced.sanitizedInput,
+      capabilityConfig: resolvedConfig.capabilityConfig,
+      sdkConfigFetchMs: resolvedConfig.sdkConfigFetchMs,
+      sdkLocalScanMs: enforced.sdkLocalScanMs
+    };
+  }
   async scanPromptInjection(input, options) {
     if (!input) {
       return;
     }
-    const capabilityConfig = await this.getCapabilityConfig(false, options);
+    const { capabilityConfig, sdkConfigFetchMs } = await this.getCapabilityConfigWithTelemetry(
+      false,
+      options
+    );
     if (!this.shouldRunLocalInjectionScan(capabilityConfig)) {
       return;
     }
@@ -2398,7 +2701,13 @@ var AgentID = class {
       aiScanEnabled: this.aiScanEnabled,
       storePii: this.storePii,
       piiManager: this.pii,
-      source: "js_sdk"
+      source: "js_sdk",
+      systemId: options?.systemId,
+      eventId: options?.clientEventId,
+      clientEventId: options?.clientEventId,
+      telemetryMetadata: buildSdkTimingMetadata({
+        sdkConfigFetchMs
+      })
     });
   }
   withMaskedOpenAIRequest(req, maskedText) {
@@ -2447,7 +2756,11 @@ var AgentID = class {
         system_id: params.systemId,
         violation_type: params.violationType,
         input_snippet: "[REDACTED_SAMPLE]",
-        action_taken: params.actionTaken
+        action_taken: params.actionTaken,
+        ...buildSdkTimingMetadata({
+          sdkConfigFetchMs: params.sdkConfigFetchMs,
+          sdkLocalScanMs: params.sdkLocalScanMs
+        })
       }
     }, { apiKey: params.apiKey });
   }
@@ -2473,6 +2786,42 @@ var AgentID = class {
       { apiKey: params.apiKey }
     );
   }
+  async finalizeIngestTelemetry(params) {
+    const controller = new AbortController();
+    const timeoutId = setTimeout(
+      () => controller.abort(),
+      Math.min(this.ingestTimeoutMs, 2e3)
+    );
+    try {
+      const response = await fetch(`${this.baseUrl}/ingest/finalize`, {
+        method: "POST",
+        headers: {
+          "Content-Type": "application/json",
+          "x-agentid-api-key": params.apiKey,
+          "x-correlation-id": params.clientEventId,
+          "X-AgentID-SDK-Version": AGENTID_SDK_VERSION_HEADER
+        },
+        body: JSON.stringify({
+          client_event_id: params.clientEventId,
+          system_id: params.systemId,
+          sdk_ingest_ms: params.sdkIngestMs
+        }),
+        signal: controller.signal
+      });
+      if (!response.ok) {
+        console.warn(
+          `[AgentID] Ingest telemetry finalize failed (status=${response.status}, client_event_id=${params.clientEventId}).`
+        );
+      }
+    } catch (error) {
+      const label = error && typeof error === "object" && error.name === "AbortError" ? "timeout" : "network";
+      console.warn(
+        `[AgentID] Ingest telemetry finalize failed (${label}, client_event_id=${params.clientEventId}).`
+      );
+    } finally {
+      clearTimeout(timeoutId);
+    }
+  }
   /**
    * GUARD: Checks limits, PII, and security before execution.
    * strictMode=false (default): FAIL-OPEN on connectivity/timeouts.
@@ -2630,15 +2979,16 @@ var AgentID = class {
     }
     return withGuardLatency({ allowed: true, reason: "guard_unreachable" });
   }
-  async sendIngest(params, options) {
+  async sendIngest(params, options, internal) {
+    const ingestStartedAt = Date.now();
     const effectiveApiKey = this.resolveApiKey(options?.apiKey);
-    const eventId = createEventId(params.event_id);
+    const transportEventId = createEventId2(internal?.transportEventId ?? params.event_id);
     const timestamp = params.timestamp ?? (/* @__PURE__ */ new Date()).toISOString();
     const metadata = {
       ...params.metadata ?? {}
     };
-    const metadataClientEventId = typeof metadata.client_event_id === "string" && isUuidLike(metadata.client_event_id) ? metadata.client_event_id : null;
-    const canonicalClientEventId = metadataClientEventId ?? eventId;
+    const metadataClientEventId = typeof metadata.client_event_id === "string" && isUuidLike2(metadata.client_event_id) ? metadata.client_event_id : null;
+    const canonicalClientEventId = metadataClientEventId ?? transportEventId;
     if (!metadataClientEventId) {
       metadata.client_event_id = canonicalClientEventId;
     }
@@ -2648,7 +2998,7 @@ var AgentID = class {
     void this.getCapabilityConfig(false, { apiKey: effectiveApiKey }).catch(() => void 0);
     const payload = {
       ...params,
-      event_id: canonicalClientEventId,
+      event_id: internal?.transportEventId ? transportEventId : canonicalClientEventId,
       timestamp,
       input: sanitizeIngestText(params.input),
       output: sanitizeIngestText(params.output),
@@ -2673,6 +3023,14 @@ var AgentID = class {
         });
         const responseBody = await safeReadJson2(response);
         if (response.ok) {
+          if (!internal?.disableFinalize) {
+            void this.finalizeIngestTelemetry({
+              apiKey: effectiveApiKey,
+              clientEventId: canonicalClientEventId,
+              systemId: params.system_id,
+              sdkIngestMs: Math.max(0, Date.now() - ingestStartedAt)
+            });
+          }
           return { ok: true, status: response.status, reason: null };
         }
         const reason = responseBody && typeof responseBody === "object" && typeof responseBody.reason === "string" ? responseBody.reason ?? null : null;
@@ -2800,8 +3158,15 @@ var AgentID = class {
    * Returns a Promise so callers can await persistence when needed.
    */
   async log(params, options) {
-    const result = await this.sendIngest(params, options);
+    const effectiveApiKey = this.resolveApiKey(options?.apiKey);
+    const requestOptions = { apiKey: effectiveApiKey };
+    const effectiveStrictMode = await this.resolveEffectiveStrictMode(requestOptions);
+    const result = await this.sendIngest(params, requestOptions);
     if (!result.ok) {
+      this.maybeRaiseStrictIngestDependencyError({
+        strictMode: effectiveStrictMode,
+        result
+      });
       console.warn(
         `[AgentID] Ingest telemetry failed (status=${result.status ?? "network"}, reason=${result.reason ?? "unknown"}).`
       );
@@ -2827,6 +3192,9 @@ var AgentID = class {
    */
   wrapOpenAI(openai, options) {
     const systemId = options.system_id;
+    const expectedLanguages = normalizeExpectedLanguages(
+      options.expected_languages ?? options.expectedLanguages
+    );
     const adapter = new OpenAIAdapter();
     const wrapChatCompletions = (chatObj) => {
       if (!chatObj || typeof chatObj !== "object") return chatObj;
@@ -2853,6 +3221,8 @@ var AgentID = class {
                 const requestLevelApiKey = options.resolveApiKey?.(req) ?? options.apiKey ?? options.api_key;
                 const effectiveApiKey = this.resolveApiKey(requestLevelApiKey);
                 const requestOptions = { apiKey: effectiveApiKey };
+                const clientEventId = this.resolveClientEventId(req);
+                const effectiveStrictMode = await this.resolveEffectiveStrictMode(requestOptions);
                 const stream = adapter.isStream(req);
                 let capabilityConfig = this.getCachedCapabilityConfig(requestOptions);
                 const userText = adapter.extractInput(req);
@@ -2861,16 +3231,19 @@ var AgentID = class {
                 let createArgs = normalizedCreateArgs;
                 let mapping = {};
                 let shouldDeanonymize = false;
+                let sdkConfigFetchMs = 0;
+                let sdkLocalScanMs = 0;
                 if (userText) {
-                  await this.scanPromptInjection(userText, requestOptions);
                   const prepared = await this.prepareInputForDispatch({
                     input: userText,
                     systemId,
                     stream,
-                    skipInjectionScan: true
+                    clientEventId
                   }, requestOptions);
                   capabilityConfig = prepared.capabilityConfig;
                   maskedText = prepared.sanitizedInput;
+                  sdkConfigFetchMs = prepared.sdkConfigFetchMs ?? 0;
+                  sdkLocalScanMs = prepared.sdkLocalScanMs ?? 0;
                   if (maskedText !== userText) {
                     maskedReq = this.withMaskedOpenAIRequest(
                       req,
@@ -2880,7 +3253,8 @@ var AgentID = class {
                     nextCreateArgs[0] = maskedReq;
                     createArgs = nextCreateArgs;
                   }
-                  if (!capabilityConfig.block_pii_leakage && this.piiMasking) {
+                  const effectivePiiMasking = this.resolveEffectivePiiMasking(capabilityConfig);
+                  if (!capabilityConfig.block_pii_leakage && effectivePiiMasking) {
                     if (stream) {
                       console.warn("AgentID: PII masking is disabled for streaming responses.");
                     } else {
@@ -2903,19 +3277,54 @@ var AgentID = class {
                     "AgentID: No user message found. Security guard requires string input."
                   );
                 }
-                const clientEventId = this.resolveClientEventId(req);
                 const verdict = await this.guard({
                   input: maskedText,
                   system_id: systemId,
                   model: adapter.getModelName(maskedReq),
                   user_id: options.user_id,
                   client_event_id: clientEventId,
-                  client_capabilities: this.buildClientCapabilities("openai", false)
+                  expected_languages: expectedLanguages,
+                  client_capabilities: this.buildClientCapabilities(
+                    "openai",
+                    false,
+                    capabilityConfig
+                  )
                 }, requestOptions);
+                let localFallbackApplied = false;
+                let localFallbackReason = null;
                 if (!verdict.allowed) {
-                  throw new SecurityBlockError(verdict.reason ?? "guard_denied");
+                  if (effectiveStrictMode && isGuardFailureEligibleForLocalFallback(verdict.reason)) {
+                    localFallbackApplied = true;
+                    localFallbackReason = verdict.reason ?? "guard_unreachable";
+                    if (sdkLocalScanMs === 0) {
+                      const fallback = await this.applyLocalPolicyChecks({
+                        input: maskedText,
+                        systemId,
+                        stream,
+                        capabilityConfig,
+                        apiKey: effectiveApiKey,
+                        clientEventId,
+                        sdkConfigFetchMs,
+                        runPromptInjectionCheck: true
+                      });
+                      maskedText = fallback.sanitizedInput;
+                      sdkLocalScanMs = fallback.sdkLocalScanMs;
+                    }
+                  } else {
+                    throw new SecurityBlockError(verdict.reason ?? "guard_denied");
+                  }
                 }
-                const canonicalClientEventId = typeof verdict.client_event_id === "string" && isUuidLike(verdict.client_event_id) ? verdict.client_event_id : clientEventId;
+                const currentRequestInput = adapter.extractInput(maskedReq);
+                if (maskedText !== currentRequestInput) {
+                  maskedReq = this.withMaskedOpenAIRequest(
+                    req,
+                    maskedText
+                  );
+                  const nextCreateArgs = [...normalizedCreateArgs];
+                  nextCreateArgs[0] = maskedReq;
+                  createArgs = nextCreateArgs;
+                }
+                const canonicalClientEventId = typeof verdict.client_event_id === "string" && isUuidLike2(verdict.client_event_id) ? verdict.client_event_id : clientEventId;
                 const guardEventId = typeof verdict.guard_event_id === "string" && verdict.guard_event_id.length > 0 ? verdict.guard_event_id : null;
                 const guardLatencyMs = typeof verdict.guard_latency_ms === "number" && Number.isFinite(verdict.guard_latency_ms) ? Math.max(0, Math.trunc(verdict.guard_latency_ms)) : Math.max(0, Date.now() - pipelineStartedAt);
                 const transparency = coerceTransparencyMetadata(verdict.transparency);
@@ -2964,16 +3373,31 @@ var AgentID = class {
                           simulated_decision: verdict.simulated_decision ?? null,
                           simulated_output_decision: isShadowMode && result.outputMasked ? "masked" : "allowed",
                           response_streamed: true,
+                          sdk_local_fallback_applied: localFallbackApplied,
+                          sdk_local_fallback_reason: localFallbackReason,
                           guard_latency_ms: guardLatencyMs,
                           model_latency_ms: modelLatencyMs2,
                           total_pipeline_latency_ms: totalPipelineLatencyMs2,
                           guard_event_id: guardEventId,
                           client_event_id: canonicalClientEventId,
-                          transparency
+                          transparency,
+                          ...buildSdkTimingMetadata({
+                            sdkConfigFetchMs,
+                            sdkLocalScanMs,
+                            sdkGuardMs: guardLatencyMs
+                          })
                         },
-                        client_capabilities: this.buildClientCapabilities("openai", false)
+                        client_capabilities: this.buildClientCapabilities(
+                          "openai",
+                          false,
+                          capabilityConfig
+                        )
                       }, requestOptions);
                       if (!ingestResult.ok) {
+                        this.maybeRaiseStrictIngestDependencyError({
+                          strictMode: effectiveStrictMode,
+                          result: ingestResult
+                        });
                         console.warn(
                           `[AgentID] Stream ingest telemetry failed (status=${ingestResult.status ?? "network"}, reason=${ingestResult.reason ?? "unknown"}).`
                         );
@@ -3015,22 +3439,37 @@ var AgentID = class {
                       simulated_decision: verdict.simulated_decision ?? null,
                       simulated_output_decision: isShadowMode && wrappedCompletion.outputMasked ? "masked" : "allowed",
                       response_streamed: false,
+                      sdk_local_fallback_applied: localFallbackApplied,
+                      sdk_local_fallback_reason: localFallbackReason,
                       guard_latency_ms: guardLatencyMs,
                       model_latency_ms: modelLatencyMs,
                       total_pipeline_latency_ms: totalPipelineLatencyMs,
                       guard_event_id: guardEventId,
                       client_event_id: canonicalClientEventId,
-                      transparency
+                      transparency,
+                      ...buildSdkTimingMetadata({
+                        sdkConfigFetchMs,
+                        sdkLocalScanMs,
+                        sdkGuardMs: guardLatencyMs
+                      })
                     },
-                    client_capabilities: this.buildClientCapabilities("openai", false)
+                    client_capabilities: this.buildClientCapabilities(
+                      "openai",
+                      false,
+                      capabilityConfig
+                    )
                   }, requestOptions);
                   if (!ingestResult.ok) {
+                    this.maybeRaiseStrictIngestDependencyError({
+                      strictMode: effectiveStrictMode,
+                      result: ingestResult
+                    });
                     console.warn(
                       `[AgentID] Ingest telemetry failed (status=${ingestResult.status ?? "network"}, reason=${ingestResult.reason ?? "unknown"}).`
                     );
                   }
                 }
-                if (!capabilityConfig.block_pii_leakage && this.piiMasking && shouldDeanonymize) {
+                if (!capabilityConfig.block_pii_leakage && this.resolveEffectivePiiMasking(capabilityConfig) && shouldDeanonymize) {
                   const deanon = this.pii.deanonymize(adapter.extractOutput(res), mapping);
                   try {
                     if (Array.isArray(res?.choices)) {
@@ -3084,7 +3523,7 @@ function normalizeBaseUrl4(baseUrl) {
   const candidate = typeof baseUrl === "string" && baseUrl.trim().length > 0 ? baseUrl.trim() : DEFAULT_BASE_URL;
   return candidate.replace(/\/+$/, "");
 }
-function createEventId2() {
+function createEventId3() {
   try {
     if (typeof globalThis !== "undefined" && globalThis.crypto?.randomUUID) {
       return globalThis.crypto.randomUUID();
@@ -3096,7 +3535,7 @@ function createEventId2() {
 }
 async function sendTransparencyBadgeRenderedTelemetry(params) {
   const timestamp = (/* @__PURE__ */ new Date()).toISOString();
-  const eventId = createEventId2();
+  const eventId = createEventId3();
   const payload = {
     event_id: eventId,
     system_id: params.telemetry.systemId,
@@ -3228,6 +3667,7 @@ function AgentIDTransparencyBadge(props) {
 0 && (module.exports = {
   AgentID,
   AgentIDTransparencyBadge,
+  DependencyError,
   InjectionScanner,
   OpenAIAdapter,
   PIIManager,