agentid-sdk 0.1.24 → 0.1.26

package/README.md

@@ -99,6 +99,7 @@ const openai = new OpenAI({ apiKey: process.env.OPENAI_API_KEY! });
 const secured = agent.wrapOpenAI(openai, {
   system_id: process.env.AGENTID_SYSTEM_ID!,
   user_id: "customer-123",
+  expected_languages: ["en"],
 });
 
 const response = await secured.chat.completions.create({
@@ -127,6 +128,7 @@ import { StringOutputParser } from "@langchain/core/output_parsers";
 const agent = new AgentID();
 const handler = new AgentIDCallbackHandler(agent, {
   system_id: process.env.AGENTID_SYSTEM_ID!,
+  expected_languages: ["en"],
 });
 
 const prompt = ChatPromptTemplate.fromTemplate("Answer in one sentence: {question}");
@@ -213,6 +215,15 @@ const agent = new AgentID({
 });
 ```
 
+### Optional client-side fast fail
+
+```ts
+const agent = new AgentID({
+  failureMode: "fail_close",
+  clientFastFail: true, // opt-in local preflight before /guard
+});
+```
+
 ### Error Handling & Strict Mode
 
 By default, AgentID is designed to keep your application running if the AgentID API has a timeout or is temporarily unreachable.
@@ -220,12 +231,14 @@ By default, AgentID is designed to keep your application running if the AgentID
 | Mode | Connectivity Failure | LLM Execution | Best For |
 | :--- | :--- | :--- | :--- |
 | **Default** (Strict Off) | API Timeout / Unreachable | **Fail-Open** (continues) | Standard SaaS, chatbots |
-| **Strict Mode** (`strictMode: true`) | API Timeout / Unreachable | **Fail-Closed** (blocks) | Healthcare, FinTech, high-risk |
+| **Strict Mode** (`strictMode: true`) | API Timeout / Unreachable | Direct `guard()` denies; wrapped flows can apply local fallback first | Healthcare, FinTech, high-risk |
 
 - `guard()` returns a verdict (`allowed`, `reason`); handle deny paths explicitly.
 - `wrapOpenAI()` and LangChain handlers throw `SecurityBlockError` when a prompt is blocked.
+- Backend `/guard` is the default authority for prompt injection, DB access, code execution, and PII leakage in SDK-wrapped flows.
+- `clientFastFail` / `client_fast_fail` is optional and disabled by default. Enable it only when you explicitly want local preflight before the backend call.
+- If backend guard is unreachable and the effective failure mode is `fail_close`, wrapped OpenAI/LangChain flows can run local fallback enforcement. Local hits still block; otherwise the request can continue with fallback telemetry attached.
 - If `strictMode` is not explicitly set in SDK code, runtime behavior follows the system configuration from AgentID (`strict_security_mode` / `failure_mode`).
-- Local prompt-injection heuristics are enabled only when dashboard policy enables injection blocking (`block_on_heuristic` / legacy injection flags). `strictMode` does not force local heuristic blocking.
 - Ingest retries transient failures (5xx/429) and logs warnings if persistence fails.
 
 ### Event Identity Model
@@ -244,10 +257,20 @@ SDK behavior:
   - `metadata.client_event_id`
   - `metadata.guard_event_id` (when available from wrappers/callbacks)
   - `x-correlation-id = client_event_id`
+- after a successful primary ingest, SDK wrappers can call `/ingest/finalize` with the same `client_event_id` to attach `sdk_ingest_ms`
 - SDK requests include `x-agentid-sdk-version` for telemetry/version diagnostics.
 
 This keeps Guard + Complete linked under one correlation key while preserving internal event linkage in the dashboard.
 
+### SDK Timing Telemetry
+
+SDK-managed metadata can include:
+
+- `sdk_config_fetch_ms`: capability/config fetch time before dispatch.
+- `sdk_local_scan_ms`: optional local enforcement time (`clientFastFail` or fail-close fallback path).
+- `sdk_guard_ms`: backend `/guard` round-trip time observed by the SDK wrapper.
+- `sdk_ingest_ms`: post-ingest transport timing finalized by the SDK through `/ingest/finalize` after a successful primary `/ingest`.
+
 ### Policy-Pack Runtime Telemetry
 
 When the backend uses compiled policy packs, runtime metadata includes:
@@ -280,9 +303,9 @@ powershell -ExecutionPolicy Bypass -File .\scripts\qa\run-ai-label-audit-check.p
 
 ## 7. Security & Compliance
 
-- Optional local PII masking and local policy enforcement before model dispatch.
-- Prompt-injection scanning in the SDK request path.
-- Guard checks run pre-execution; ingest telemetry captures prompt/output lifecycle.
+- Backend `/guard` remains the primary enforcement authority by default.
+- Optional local PII masking and opt-in `clientFastFail` are available for edge cases.
+- Guard checks run pre-execution; ingest + finalize telemetry captures prompt/output lifecycle and SDK timing breakdowns.
 - Safe for server and serverless runtimes (including async completion flows).
 - Supports compliance and forensics workflows with durable event records.
 

package/dist/{agentid-BGCUoYV7.d.mts → agentid-DviYzyAM.d.mts}

@@ -5,6 +5,7 @@ type CapabilityConfig = {
     block_on_heuristic: boolean;
     inject_transparency_metadata: boolean;
     block_pii_leakage: boolean;
+    enable_sdk_pii_masking?: boolean;
     block_db_access: boolean;
     block_code_execution: boolean;
     block_toxicity: boolean;
@@ -37,9 +38,14 @@ interface GuardResponse {
     simulated_decision?: "allowed" | "masked" | "blocked";
     shadow_blocked?: boolean;
     policy_pack_matcher_backend?: "rust_wasm" | "js_hybrid" | "legacy_fallback";
-    policy_pack_scan_profile?: "expected_languages" | "core_en_fallback";
+    policy_pack_scan_profile?: "expected_languages" | "auto_detected" | "global_high_priority" | "core_en_fallback";
     policy_pack_scan_mode?: "full" | "segmented";
     exotic_language_detected?: boolean;
+    langid_primary?: string;
+    langid_confidence?: "high" | "medium" | "low";
+    langid_secondary?: string[];
+    langid_mixed?: boolean;
+    langid_source?: "input_detection" | "input_detection_with_hint";
     transparency?: TransparencyMetadata;
 }
 interface TransparencyMetadata {
@@ -51,6 +57,10 @@ interface TransparencyMetadata {
 interface RequestOptions {
     apiKey?: string;
 }
+type InjectionScanRequestOptions = RequestOptions & {
+    clientEventId?: string;
+    systemId?: string;
+};
 interface LogParams {
     event_id?: string;
     system_id?: string;
@@ -78,9 +88,12 @@ type AgentIDConfig = {
     baseUrl?: string;
     piiMasking?: boolean;
     checkInjection?: boolean;
+    clientFastFail?: boolean;
+    client_fast_fail?: boolean;
     aiScanEnabled?: boolean;
     storePii?: boolean;
     strictMode?: boolean;
+    failureMode?: "fail_open" | "fail_close";
     guardTimeoutMs?: number;
     ingestTimeoutMs?: number;
 };
@@ -88,19 +101,33 @@ type AgentIDConfig = {
 type PreparedInput = {
     sanitizedInput: string;
     capabilityConfig: CapabilityConfig;
+    sdkConfigFetchMs?: number;
+    sdkLocalScanMs?: number;
 };
 declare class SecurityBlockError extends Error {
     reason: string;
     constructor(reason?: string);
 }
+declare class DependencyError extends Error {
+    dependency: "ingest";
+    reason: string;
+    status: number | null;
+    constructor(params: {
+        dependency: "ingest";
+        reason: string;
+        status: number | null;
+    });
+}
 declare class AgentID {
     private baseUrl;
     private apiKey;
-    private piiMasking;
+    private configuredPiiMasking;
     private checkInjection;
+    private clientFastFail;
     private aiScanEnabled;
     private storePii;
     private strictMode;
+    private configuredFailureMode;
     private guardTimeoutMs;
     private ingestTimeoutMs;
     private pii;
@@ -108,6 +135,9 @@ declare class AgentID {
     private injectionScanner;
     private recentGuardVerdicts;
     constructor(config?: AgentIDConfig);
+    get piiMasking(): boolean | undefined;
+    private resolveEffectivePiiMasking;
+    getEffectivePiiMasking(options?: RequestOptions): boolean;
     private buildClientCapabilities;
     private resolveApiKey;
     private resolveClientEventId;
@@ -115,19 +145,32 @@ declare class AgentID {
     private readCachedGuardVerdict;
     private cacheGuardVerdict;
     getCapabilityConfig(force?: boolean, options?: RequestOptions): Promise<CapabilityConfig>;
+    private getCapabilityConfigWithTelemetry;
     private getCachedCapabilityConfig;
     private resolveEffectiveStrictMode;
+    private maybeRaiseStrictIngestDependencyError;
     private shouldRunLocalInjectionScan;
+    private applyLocalPolicyChecks;
     prepareInputForDispatch(params: {
         input: string;
         systemId: string;
         stream: boolean;
         skipInjectionScan?: boolean;
+        clientEventId?: string;
+    }, options?: RequestOptions): Promise<PreparedInput>;
+    applyLocalFallbackForGuardFailure(params: {
+        input: string;
+        systemId: string;
+        stream: boolean;
+        clientEventId?: string;
+        capabilityConfig?: CapabilityConfig;
+        sdkConfigFetchMs?: number;
     }, options?: RequestOptions): Promise<PreparedInput>;
-    scanPromptInjection(input: string, options?: RequestOptions): Promise<void>;
+    scanPromptInjection(input: string, options?: InjectionScanRequestOptions): Promise<void>;
     private withMaskedOpenAIRequest;
     private logSecurityPolicyViolation;
     private logGuardFallback;
+    private finalizeIngestTelemetry;
     /**
      * GUARD: Checks limits, PII, and security before execution.
      * strictMode=false (default): FAIL-OPEN on connectivity/timeouts.
@@ -159,10 +202,12 @@ declare class AgentID {
     wrapOpenAI<T>(openai: T, options: {
         system_id: string;
         user_id?: string;
+        expected_languages?: string[];
+        expectedLanguages?: string[];
         apiKey?: string;
         api_key?: string;
         resolveApiKey?: (request: Record<string, unknown>) => string | undefined;
     }): T;
 }
 
-export { AgentID as A, type GuardParams as G, type LogParams as L, type PreparedInput as P, type RequestOptions as R, SecurityBlockError as S, type TransparencyMetadata as T, type GuardResponse as a };
+export { AgentID as A, DependencyError as D, type GuardParams as G, type LogParams as L, type PreparedInput as P, type RequestOptions as R, SecurityBlockError as S, type TransparencyMetadata as T, type GuardResponse as a };

package/dist/{agentid-BGCUoYV7.d.ts → agentid-DviYzyAM.d.ts}

@@ -5,6 +5,7 @@ type CapabilityConfig = {
     block_on_heuristic: boolean;
     inject_transparency_metadata: boolean;
     block_pii_leakage: boolean;
+    enable_sdk_pii_masking?: boolean;
     block_db_access: boolean;
     block_code_execution: boolean;
     block_toxicity: boolean;
@@ -37,9 +38,14 @@ interface GuardResponse {
     simulated_decision?: "allowed" | "masked" | "blocked";
     shadow_blocked?: boolean;
     policy_pack_matcher_backend?: "rust_wasm" | "js_hybrid" | "legacy_fallback";
-    policy_pack_scan_profile?: "expected_languages" | "core_en_fallback";
+    policy_pack_scan_profile?: "expected_languages" | "auto_detected" | "global_high_priority" | "core_en_fallback";
     policy_pack_scan_mode?: "full" | "segmented";
     exotic_language_detected?: boolean;
+    langid_primary?: string;
+    langid_confidence?: "high" | "medium" | "low";
+    langid_secondary?: string[];
+    langid_mixed?: boolean;
+    langid_source?: "input_detection" | "input_detection_with_hint";
     transparency?: TransparencyMetadata;
 }
 interface TransparencyMetadata {
@@ -51,6 +57,10 @@ interface TransparencyMetadata {
 interface RequestOptions {
     apiKey?: string;
 }
+type InjectionScanRequestOptions = RequestOptions & {
+    clientEventId?: string;
+    systemId?: string;
+};
 interface LogParams {
     event_id?: string;
     system_id?: string;
@@ -78,9 +88,12 @@ type AgentIDConfig = {
     baseUrl?: string;
     piiMasking?: boolean;
     checkInjection?: boolean;
+    clientFastFail?: boolean;
+    client_fast_fail?: boolean;
     aiScanEnabled?: boolean;
     storePii?: boolean;
     strictMode?: boolean;
+    failureMode?: "fail_open" | "fail_close";
     guardTimeoutMs?: number;
     ingestTimeoutMs?: number;
 };
@@ -88,19 +101,33 @@ type AgentIDConfig = {
 type PreparedInput = {
     sanitizedInput: string;
     capabilityConfig: CapabilityConfig;
+    sdkConfigFetchMs?: number;
+    sdkLocalScanMs?: number;
 };
 declare class SecurityBlockError extends Error {
     reason: string;
     constructor(reason?: string);
 }
+declare class DependencyError extends Error {
+    dependency: "ingest";
+    reason: string;
+    status: number | null;
+    constructor(params: {
+        dependency: "ingest";
+        reason: string;
+        status: number | null;
+    });
+}
 declare class AgentID {
     private baseUrl;
     private apiKey;
-    private piiMasking;
+    private configuredPiiMasking;
     private checkInjection;
+    private clientFastFail;
     private aiScanEnabled;
     private storePii;
     private strictMode;
+    private configuredFailureMode;
     private guardTimeoutMs;
     private ingestTimeoutMs;
     private pii;
@@ -108,6 +135,9 @@ declare class AgentID {
     private injectionScanner;
     private recentGuardVerdicts;
     constructor(config?: AgentIDConfig);
+    get piiMasking(): boolean | undefined;
+    private resolveEffectivePiiMasking;
+    getEffectivePiiMasking(options?: RequestOptions): boolean;
     private buildClientCapabilities;
     private resolveApiKey;
     private resolveClientEventId;
@@ -115,19 +145,32 @@ declare class AgentID {
     private readCachedGuardVerdict;
     private cacheGuardVerdict;
     getCapabilityConfig(force?: boolean, options?: RequestOptions): Promise<CapabilityConfig>;
+    private getCapabilityConfigWithTelemetry;
     private getCachedCapabilityConfig;
     private resolveEffectiveStrictMode;
+    private maybeRaiseStrictIngestDependencyError;
     private shouldRunLocalInjectionScan;
+    private applyLocalPolicyChecks;
     prepareInputForDispatch(params: {
         input: string;
         systemId: string;
         stream: boolean;
         skipInjectionScan?: boolean;
+        clientEventId?: string;
+    }, options?: RequestOptions): Promise<PreparedInput>;
+    applyLocalFallbackForGuardFailure(params: {
+        input: string;
+        systemId: string;
+        stream: boolean;
+        clientEventId?: string;
+        capabilityConfig?: CapabilityConfig;
+        sdkConfigFetchMs?: number;
     }, options?: RequestOptions): Promise<PreparedInput>;
-    scanPromptInjection(input: string, options?: RequestOptions): Promise<void>;
+    scanPromptInjection(input: string, options?: InjectionScanRequestOptions): Promise<void>;
     private withMaskedOpenAIRequest;
     private logSecurityPolicyViolation;
     private logGuardFallback;
+    private finalizeIngestTelemetry;
     /**
      * GUARD: Checks limits, PII, and security before execution.
      * strictMode=false (default): FAIL-OPEN on connectivity/timeouts.
@@ -159,10 +202,12 @@ declare class AgentID {
     wrapOpenAI<T>(openai: T, options: {
         system_id: string;
         user_id?: string;
+        expected_languages?: string[];
+        expectedLanguages?: string[];
         apiKey?: string;
         api_key?: string;
         resolveApiKey?: (request: Record<string, unknown>) => string | undefined;
     }): T;
 }
 
-export { AgentID as A, type GuardParams as G, type LogParams as L, type PreparedInput as P, type RequestOptions as R, SecurityBlockError as S, type TransparencyMetadata as T, type GuardResponse as a };
+export { AgentID as A, DependencyError as D, type GuardParams as G, type LogParams as L, type PreparedInput as P, type RequestOptions as R, SecurityBlockError as S, type TransparencyMetadata as T, type GuardResponse as a };