agentid-sdk 0.1.25 → 0.1.26

package/README.md

@@ -215,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.
@@ -222,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
@@ -246,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:
@@ -282,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-B5Y1g2Ko.d.mts → agentid-DviYzyAM.d.mts}

@@ -88,6 +88,8 @@ type AgentIDConfig = {
     baseUrl?: string;
     piiMasking?: boolean;
     checkInjection?: boolean;
+    clientFastFail?: boolean;
+    client_fast_fail?: boolean;
     aiScanEnabled?: boolean;
     storePii?: boolean;
     strictMode?: boolean;
@@ -99,6 +101,8 @@ type AgentIDConfig = {
 type PreparedInput = {
     sanitizedInput: string;
     capabilityConfig: CapabilityConfig;
+    sdkConfigFetchMs?: number;
+    sdkLocalScanMs?: number;
 };
 declare class SecurityBlockError extends Error {
     reason: string;
@@ -119,6 +123,7 @@ declare class AgentID {
     private apiKey;
     private configuredPiiMasking;
     private checkInjection;
+    private clientFastFail;
     private aiScanEnabled;
     private storePii;
     private strictMode;
@@ -140,20 +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?: 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.

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

@@ -88,6 +88,8 @@ type AgentIDConfig = {
     baseUrl?: string;
     piiMasking?: boolean;
     checkInjection?: boolean;
+    clientFastFail?: boolean;
+    client_fast_fail?: boolean;
     aiScanEnabled?: boolean;
     storePii?: boolean;
     strictMode?: boolean;
@@ -99,6 +101,8 @@ type AgentIDConfig = {
 type PreparedInput = {
     sanitizedInput: string;
     capabilityConfig: CapabilityConfig;
+    sdkConfigFetchMs?: number;
+    sdkLocalScanMs?: number;
 };
 declare class SecurityBlockError extends Error {
     reason: string;
@@ -119,6 +123,7 @@ declare class AgentID {
     private apiKey;
     private configuredPiiMasking;
     private checkInjection;
+    private clientFastFail;
     private aiScanEnabled;
     private storePii;
     private strictMode;
@@ -140,20 +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?: 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.