agentid-sdk 0.1.25 → 0.1.28

package/README.md

@@ -110,6 +110,8 @@ const response = await secured.chat.completions.create({
 console.log(response.choices[0]?.message?.content ?? "");
 ```
 
+Wrapped OpenAI calls persist telemetry for both regular and streamed completions. For `stream: true`, logging happens when the stream finishes.
+
 > Scope note: AgentID compliance/risk controls apply to the specific SDK-wrapped LLM calls (`guard()`, `wrapOpenAI()`, LangChain callback-wrapped flows). They do not automatically classify unrelated code paths in your whole monolithic application.
 
 ### LangChain Integration
@@ -145,6 +147,8 @@ const result = await chain.invoke(
 console.log(result);
 ```
 
+LangChain callbacks log on run completion. Token/cost telemetry for streamed chains depends on the provider exposing usage in the final LangChain result.
+
 ### Raw Ingest API (Telemetry Only)
 
 ```ts
@@ -215,6 +219,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 +235,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 +261,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 +307,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-agvYW2vW.d.mts}

@@ -18,6 +18,7 @@ interface GuardParams {
     user_id?: string;
     client_event_id?: string;
     expected_languages?: string[];
+    request_identity?: Record<string, unknown>;
     client_capabilities?: {
         capabilities: {
             has_feedback_handler: boolean;
@@ -67,10 +68,11 @@ interface LogParams {
     input: string;
     output: string;
     model: string;
-    usage?: Record<string, number>;
-    tokens?: Record<string, number>;
+    usage?: Record<string, unknown>;
+    tokens?: Record<string, unknown>;
     latency?: number;
     user_id?: string;
+    request_identity?: Record<string, unknown>;
     metadata?: Record<string, unknown>;
     event_type?: "start" | "complete" | "error" | "human_override" | "security_alert" | "security_block" | "security_policy_violation" | "transparency_badge_rendered";
     severity?: "info" | "warning" | "error" | "high";
@@ -88,6 +90,8 @@ type AgentIDConfig = {
     baseUrl?: string;
     piiMasking?: boolean;
     checkInjection?: boolean;
+    clientFastFail?: boolean;
+    client_fast_fail?: boolean;
     aiScanEnabled?: boolean;
     storePii?: boolean;
     strictMode?: boolean;
@@ -99,6 +103,8 @@ type AgentIDConfig = {
 type PreparedInput = {
     sanitizedInput: string;
     capabilityConfig: CapabilityConfig;
+    sdkConfigFetchMs?: number;
+    sdkLocalScanMs?: number;
 };
 declare class SecurityBlockError extends Error {
     reason: string;
@@ -119,6 +125,7 @@ declare class AgentID {
     private apiKey;
     private configuredPiiMasking;
     private checkInjection;
+    private clientFastFail;
     private aiScanEnabled;
     private storePii;
     private strictMode;
@@ -140,20 +147,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.
@@ -162,6 +181,7 @@ declare class AgentID {
     guard(params: GuardParams, options?: RequestOptions): Promise<GuardResponse>;
     private sendIngest;
     private extractStreamChunkText;
+    private extractStreamChunkUsage;
     private wrapCompletion;
     /**
      * LOG: Sends telemetry after execution.
@@ -180,13 +200,14 @@ declare class AgentID {
      * Wrap an OpenAI client once; AgentID will automatically:
      * - run guard() before chat.completions.create
      * - measure latency
-     * - fire-and-forget ingest logging
+     * - persist ingest telemetry for the wrapped call
      */
     wrapOpenAI<T>(openai: T, options: {
         system_id: string;
         user_id?: string;
         expected_languages?: string[];
         expectedLanguages?: string[];
+        request_identity?: Record<string, unknown>;
         apiKey?: string;
         api_key?: string;
         resolveApiKey?: (request: Record<string, unknown>) => string | undefined;

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

@@ -18,6 +18,7 @@ interface GuardParams {
     user_id?: string;
     client_event_id?: string;
     expected_languages?: string[];
+    request_identity?: Record<string, unknown>;
     client_capabilities?: {
         capabilities: {
             has_feedback_handler: boolean;
@@ -67,10 +68,11 @@ interface LogParams {
     input: string;
     output: string;
     model: string;
-    usage?: Record<string, number>;
-    tokens?: Record<string, number>;
+    usage?: Record<string, unknown>;
+    tokens?: Record<string, unknown>;
     latency?: number;
     user_id?: string;
+    request_identity?: Record<string, unknown>;
     metadata?: Record<string, unknown>;
     event_type?: "start" | "complete" | "error" | "human_override" | "security_alert" | "security_block" | "security_policy_violation" | "transparency_badge_rendered";
     severity?: "info" | "warning" | "error" | "high";
@@ -88,6 +90,8 @@ type AgentIDConfig = {
     baseUrl?: string;
     piiMasking?: boolean;
     checkInjection?: boolean;
+    clientFastFail?: boolean;
+    client_fast_fail?: boolean;
     aiScanEnabled?: boolean;
     storePii?: boolean;
     strictMode?: boolean;
@@ -99,6 +103,8 @@ type AgentIDConfig = {
 type PreparedInput = {
     sanitizedInput: string;
     capabilityConfig: CapabilityConfig;
+    sdkConfigFetchMs?: number;
+    sdkLocalScanMs?: number;
 };
 declare class SecurityBlockError extends Error {
     reason: string;
@@ -119,6 +125,7 @@ declare class AgentID {
     private apiKey;
     private configuredPiiMasking;
     private checkInjection;
+    private clientFastFail;
     private aiScanEnabled;
     private storePii;
     private strictMode;
@@ -140,20 +147,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.
@@ -162,6 +181,7 @@ declare class AgentID {
     guard(params: GuardParams, options?: RequestOptions): Promise<GuardResponse>;
     private sendIngest;
     private extractStreamChunkText;
+    private extractStreamChunkUsage;
     private wrapCompletion;
     /**
      * LOG: Sends telemetry after execution.
@@ -180,13 +200,14 @@ declare class AgentID {
      * Wrap an OpenAI client once; AgentID will automatically:
      * - run guard() before chat.completions.create
      * - measure latency
-     * - fire-and-forget ingest logging
+     * - persist ingest telemetry for the wrapped call
      */
     wrapOpenAI<T>(openai: T, options: {
         system_id: string;
         user_id?: string;
         expected_languages?: string[];
         expectedLanguages?: string[];
+        request_identity?: Record<string, unknown>;
         apiKey?: string;
         api_key?: string;
         resolveApiKey?: (request: Record<string, unknown>) => string | undefined;