agentid-sdk 0.1.22 → 0.1.24

package/README.md

@@ -109,6 +109,8 @@ const response = await secured.chat.completions.create({
 console.log(response.choices[0]?.message?.content ?? "");
 ```
 
+> 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
 
 ```bash
@@ -159,6 +161,27 @@ await agent.log({
 });
 ```
 
+### Transparency Badge (Article 50 UI Evidence)
+
+When rendering disclosure UI, log proof-of-render telemetry so you can demonstrate the end-user actually saw the badge.
+
+```tsx
+import { AgentIDTransparencyBadge } from "agentid-sdk";
+
+<AgentIDTransparencyBadge
+  telemetry={{
+    systemId: process.env.NEXT_PUBLIC_AGENTID_SYSTEM_ID!,
+    // Prefer a backend relay endpoint so no secret key is exposed in browser code.
+    ingestUrl: "/api/agentid/transparency-render",
+    headers: { "x-agentid-system-id": process.env.NEXT_PUBLIC_AGENTID_SYSTEM_ID! },
+    userId: "customer-123",
+  }}
+  placement="chat-header"
+/>;
+```
+
+On mount, the component asynchronously emits `event_type: "transparency_badge_rendered"` to the AgentID ingest endpoint.
+
 ## 6. Advanced Configuration
 
 ### Custom identity / role metadata
@@ -205,6 +228,56 @@ By default, AgentID is designed to keep your application running if the AgentID
 - 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
+
+For consistent lifecycle correlation in Activity/Prompts, use this model:
+
+- `client_event_id`: external correlation ID for one end-to-end action.
+- `guard_event_id`: ID of the preflight guard event returned by `guard()`.
+- `event_id` on `log()`: idempotency key for ingest. In the JS SDK it is canonicalized to `client_event_id` for stable one-row lifecycle updates.
+
+SDK behavior:
+
+- `guard()` sends `client_event_id` and returns canonical `client_event_id` + `guard_event_id`.
+- `log()` sends:
+  - `event_id = canonical client_event_id`
+  - `metadata.client_event_id`
+  - `metadata.guard_event_id` (when available from wrappers/callbacks)
+  - `x-correlation-id = client_event_id`
+- 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.
+
+### Policy-Pack Runtime Telemetry
+
+When the backend uses compiled policy packs, runtime metadata includes:
+
+- `policy_pack_version`: active compiled artifact version.
+- `policy_pack_fallback`: `true` means fallback detector path was used.
+- `policy_pack_details`: optional diagnostic detail for fallback/decision trace.
+
+Latency interpretation:
+
+- Activity `Latency (ms)` maps to synchronous processing (`processing_time_ms`).
+- Async AI audit time is separate (`ai_audit_duration_ms`) and can be higher.
+- First request after warm-up boundaries can be slower than steady-state requests.
+
+### Monorepo QA Commands (Maintainers)
+
+If you are validating runtime in the AgentID monorepo:
+
+```bash
+npm run qa:policy-pack-bootstrap -- --base-url=http://127.0.0.1:3000/api/v1 --system-id=<SYSTEM_UUID>
+npm run bench:policy-pack-hotpath
+```
+
+PowerShell diagnostics:
+
+```powershell
+powershell -ExecutionPolicy Bypass -File .\scripts\qa\run-guard-diagnostic.ps1 -BaseUrl http://127.0.0.1:3000/api/v1 -ApiKey $env:AGENTID_API_KEY -SystemId $env:AGENTID_SYSTEM_ID -SkipBenchmark
+powershell -ExecutionPolicy Bypass -File .\scripts\qa\run-ai-label-audit-check.ps1 -BaseUrl http://127.0.0.1:3000/api/v1 -ApiKey $env:AGENTID_API_KEY -SystemId $env:AGENTID_SYSTEM_ID -Model gpt-4o-mini
+```
+
 ## 7. Security & Compliance
 
 - Optional local PII masking and local policy enforcement before model dispatch.

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

@@ -3,6 +3,7 @@ type CapabilityConfig = {
     strict_security_mode: boolean;
     failure_mode: "fail_open" | "fail_close";
     block_on_heuristic: boolean;
+    inject_transparency_metadata: boolean;
     block_pii_leakage: boolean;
     block_db_access: boolean;
     block_code_execution: boolean;
@@ -15,6 +16,7 @@ interface GuardParams {
     model?: string;
     user_id?: string;
     client_event_id?: string;
+    expected_languages?: string[];
     client_capabilities?: {
         capabilities: {
             has_feedback_handler: boolean;
@@ -30,8 +32,21 @@ interface GuardResponse {
     transformed_input?: string;
     guard_event_id?: string;
     client_event_id?: string;
+    guard_latency_ms?: number;
     shadow_mode?: boolean;
     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_mode?: "full" | "segmented";
+    exotic_language_detected?: boolean;
+    transparency?: TransparencyMetadata;
+}
+interface TransparencyMetadata {
+    is_ai_generated: true;
+    disclosure: "You are interacting with an AI.";
+    article: "EU_AI_ACT_ARTICLE_50";
+    injection_mode: "deterministic";
 }
 interface RequestOptions {
     apiKey?: string;
@@ -47,7 +62,7 @@ interface LogParams {
     latency?: number;
     user_id?: string;
     metadata?: Record<string, unknown>;
-    event_type?: "start" | "complete" | "error" | "human_override" | "security_alert" | "security_block" | "security_policy_violation";
+    event_type?: "start" | "complete" | "error" | "human_override" | "security_alert" | "security_block" | "security_policy_violation" | "transparency_badge_rendered";
     severity?: "info" | "warning" | "error" | "high";
     timestamp?: string;
     client_capabilities?: {
@@ -150,4 +165,4 @@ declare class AgentID {
     }): 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 GuardResponse as a };
+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 };

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

@@ -3,6 +3,7 @@ type CapabilityConfig = {
     strict_security_mode: boolean;
     failure_mode: "fail_open" | "fail_close";
     block_on_heuristic: boolean;
+    inject_transparency_metadata: boolean;
     block_pii_leakage: boolean;
     block_db_access: boolean;
     block_code_execution: boolean;
@@ -15,6 +16,7 @@ interface GuardParams {
     model?: string;
     user_id?: string;
     client_event_id?: string;
+    expected_languages?: string[];
     client_capabilities?: {
         capabilities: {
             has_feedback_handler: boolean;
@@ -30,8 +32,21 @@ interface GuardResponse {
     transformed_input?: string;
     guard_event_id?: string;
     client_event_id?: string;
+    guard_latency_ms?: number;
     shadow_mode?: boolean;
     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_mode?: "full" | "segmented";
+    exotic_language_detected?: boolean;
+    transparency?: TransparencyMetadata;
+}
+interface TransparencyMetadata {
+    is_ai_generated: true;
+    disclosure: "You are interacting with an AI.";
+    article: "EU_AI_ACT_ARTICLE_50";
+    injection_mode: "deterministic";
 }
 interface RequestOptions {
     apiKey?: string;
@@ -47,7 +62,7 @@ interface LogParams {
     latency?: number;
     user_id?: string;
     metadata?: Record<string, unknown>;
-    event_type?: "start" | "complete" | "error" | "human_override" | "security_alert" | "security_block" | "security_policy_violation";
+    event_type?: "start" | "complete" | "error" | "human_override" | "security_alert" | "security_block" | "security_policy_violation" | "transparency_badge_rendered";
     severity?: "info" | "warning" | "error" | "high";
     timestamp?: string;
     client_capabilities?: {
@@ -150,4 +165,4 @@ declare class AgentID {
     }): 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 GuardResponse as a };
+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 };