agentid-sdk 0.1.19 → 0.1.21

package/README.md

@@ -9,6 +9,23 @@
 
 `agentid-sdk` is the official Node.js/TypeScript SDK for AgentID, an AI security and compliance System of Record. It allows you to gate LLM traffic through guard checks, enforce policy before execution, and capture durable telemetry for audit and governance workflows.
 
+### The Mental Model
+
+AgentID sits between your application and the LLM runtime:
+
+```text
+User Input -> guard() -> [AgentID Policy] -> verdict
+                              | allowed
+                              v
+                         LLM Provider
+                              v
+                           log() -> [Immutable Ledger]
+```
+
+- `guard()`: evaluates prompt and context before model execution.
+- Model call: executes only if guard verdict is allowed.
+- `log()`: persists immutable telemetry (prompt, output, latency) for audit and compliance.
+
 ## 2. Installation
 
 ```bash
@@ -30,6 +47,12 @@ export AGENTID_SYSTEM_ID="00000000-0000-0000-0000-000000000000"
 export OPENAI_API_KEY="sk-proj-..."
 ```
 
+### Compatibility
+
+- **Node.js:** v18+ / **Python:** 3.9+ (cross-SDK matrix)
+- **Thread Safety:** AgentID clients are thread-safe and intended to be instantiated once and reused across concurrent requests.
+- **Latency:** async `log()` is non-blocking for model execution paths; sync `guard()` typically adds network latency (commonly ~50-100ms, environment-dependent).
+
 ## 4. Quickstart
 
 ```ts
@@ -163,16 +186,23 @@ await agent.log({
 const agent = new AgentID({
   strictMode: true,      // fail-closed on guard connectivity/timeouts
   guardTimeoutMs: 10000, // default guard timeout is 10000ms
+  ingestTimeoutMs: 10000 // default ingest timeout is 10000ms
 });
 ```
 
-### Error handling behavior
+### 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.
+
+| 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 |
 
 - `guard()` returns a verdict (`allowed`, `reason`); handle deny paths explicitly.
-- `wrapOpenAI()` throws `Error("AgentID: Security Blocked (...)")` when blocked.
-- Default mode is fail-open for connectivity/timeouts (`timeout_fallback`, `guard_unreachable`, `system_failure_fail_open`).
+- `wrapOpenAI()` and LangChain handlers throw `SecurityBlockError` when a prompt is blocked.
 - If `strictMode` is not explicitly set in SDK code, runtime behavior follows the system configuration from AgentID (`strict_security_mode` / `failure_mode`).
-- Set `strictMode: true` to fail-closed (`network_error_strict_mode` / `server_error`) in high-sensitivity environments.
+- 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.
 
 ## 7. Security & Compliance

package/dist/{langchain-DJDqqpbT.d.mts → agentid-BmsXTOCc.d.mts}

@@ -1,9 +1,8 @@
-import { BaseCallbackHandler } from '@langchain/core/callbacks/base';
-
 type CapabilityConfig = {
     shadow_mode: boolean;
     strict_security_mode: boolean;
     failure_mode: "fail_open" | "fail_close";
+    block_on_heuristic: boolean;
     block_pii_leakage: boolean;
     block_db_access: boolean;
     block_code_execution: boolean;
@@ -68,12 +67,17 @@ type AgentIDConfig = {
     storePii?: boolean;
     strictMode?: boolean;
     guardTimeoutMs?: number;
+    ingestTimeoutMs?: number;
 };
 
 type PreparedInput = {
     sanitizedInput: string;
     capabilityConfig: CapabilityConfig;
 };
+declare class SecurityBlockError extends Error {
+    reason: string;
+    constructor(reason?: string);
+}
 declare class AgentID {
     private baseUrl;
     private apiKey;
@@ -83,6 +87,7 @@ declare class AgentID {
     private storePii;
     private strictMode;
     private guardTimeoutMs;
+    private ingestTimeoutMs;
     private pii;
     private localEnforcer;
     private injectionScanner;
@@ -97,6 +102,7 @@ declare class AgentID {
     getCapabilityConfig(force?: boolean, options?: RequestOptions): Promise<CapabilityConfig>;
     private getCachedCapabilityConfig;
     private resolveEffectiveStrictMode;
+    private shouldRunLocalInjectionScan;
     prepareInputForDispatch(params: {
         input: string;
         systemId: string;
@@ -144,30 +150,4 @@ declare class AgentID {
     }): T;
 }
 
-/**
- * LangChainJS callback handler (dependency-free shape).
- *
- * Usage (LangChain):
- * callbacks: [new AgentIDCallbackHandler(agent, { system_id: "..." })]
- */
-declare class AgentIDCallbackHandler extends BaseCallbackHandler {
-    name: string;
-    private agent;
-    private systemId;
-    private apiKeyOverride?;
-    private runs;
-    constructor(agent: AgentID, options: {
-        system_id: string;
-        apiKey?: string;
-        api_key?: string;
-    });
-    private get requestOptions();
-    private getLangchainCapabilities;
-    private preflight;
-    handleLLMStart(serialized: unknown, prompts: unknown, runId?: string, _parentRunId?: string, extraParams?: unknown): Promise<void>;
-    handleChatModelStart(serialized: unknown, messages: unknown, runId?: string, _parentRunId?: string, extraParams?: unknown): Promise<void>;
-    handleLLMEnd(output: unknown, runId?: string): Promise<void>;
-    handleLLMError(err: unknown, runId?: string): Promise<void>;
-}
-
-export { AgentID as A, type GuardParams as G, type LogParams as L, type PreparedInput as P, type RequestOptions as R, AgentIDCallbackHandler as a, type GuardResponse as b };
+export { AgentID as A, type GuardParams as G, type LogParams as L, type PreparedInput as P, type RequestOptions as R, SecurityBlockError as S, type GuardResponse as a };

package/dist/{langchain-DJDqqpbT.d.ts → agentid-BmsXTOCc.d.ts}

@@ -1,9 +1,8 @@
-import { BaseCallbackHandler } from '@langchain/core/callbacks/base';
-
 type CapabilityConfig = {
     shadow_mode: boolean;
     strict_security_mode: boolean;
     failure_mode: "fail_open" | "fail_close";
+    block_on_heuristic: boolean;
     block_pii_leakage: boolean;
     block_db_access: boolean;
     block_code_execution: boolean;
@@ -68,12 +67,17 @@ type AgentIDConfig = {
     storePii?: boolean;
     strictMode?: boolean;
     guardTimeoutMs?: number;
+    ingestTimeoutMs?: number;
 };
 
 type PreparedInput = {
     sanitizedInput: string;
     capabilityConfig: CapabilityConfig;
 };
+declare class SecurityBlockError extends Error {
+    reason: string;
+    constructor(reason?: string);
+}
 declare class AgentID {
     private baseUrl;
     private apiKey;
@@ -83,6 +87,7 @@ declare class AgentID {
     private storePii;
     private strictMode;
     private guardTimeoutMs;
+    private ingestTimeoutMs;
     private pii;
     private localEnforcer;
     private injectionScanner;
@@ -97,6 +102,7 @@ declare class AgentID {
     getCapabilityConfig(force?: boolean, options?: RequestOptions): Promise<CapabilityConfig>;
     private getCachedCapabilityConfig;
     private resolveEffectiveStrictMode;
+    private shouldRunLocalInjectionScan;
     prepareInputForDispatch(params: {
         input: string;
         systemId: string;
@@ -144,30 +150,4 @@ declare class AgentID {
     }): T;
 }
 
-/**
- * LangChainJS callback handler (dependency-free shape).
- *
- * Usage (LangChain):
- * callbacks: [new AgentIDCallbackHandler(agent, { system_id: "..." })]
- */
-declare class AgentIDCallbackHandler extends BaseCallbackHandler {
-    name: string;
-    private agent;
-    private systemId;
-    private apiKeyOverride?;
-    private runs;
-    constructor(agent: AgentID, options: {
-        system_id: string;
-        apiKey?: string;
-        api_key?: string;
-    });
-    private get requestOptions();
-    private getLangchainCapabilities;
-    private preflight;
-    handleLLMStart(serialized: unknown, prompts: unknown, runId?: string, _parentRunId?: string, extraParams?: unknown): Promise<void>;
-    handleChatModelStart(serialized: unknown, messages: unknown, runId?: string, _parentRunId?: string, extraParams?: unknown): Promise<void>;
-    handleLLMEnd(output: unknown, runId?: string): Promise<void>;
-    handleLLMError(err: unknown, runId?: string): Promise<void>;
-}
-
-export { AgentID as A, type GuardParams as G, type LogParams as L, type PreparedInput as P, type RequestOptions as R, AgentIDCallbackHandler as a, type GuardResponse as b };
+export { AgentID as A, type GuardParams as G, type LogParams as L, type PreparedInput as P, type RequestOptions as R, SecurityBlockError as S, type GuardResponse as a };