agentid-sdk 0.1.40 → 0.1.42

package/README.md

@@ -22,7 +22,7 @@ User Input -> guard() -> [AgentID Policy] -> verdict
                            log() -> [Immutable Ledger]
 ```
 
-- `guard()`: evaluates prompt and context before model execution.
+- `guard()`: evaluates prompt and context once per model invocation before model execution. For chat flows, that single invocation can include the full protected history.
 - Model call: executes only if guard verdict is allowed.
 - `log()`: persists immutable telemetry (prompt, output, latency) for audit and compliance.
 
@@ -129,6 +129,22 @@ forwarded to the model provider. The wrapper also protects returned completion
 text before it is logged or returned from the wrapped call when SDK-side masking
 is enabled.
 
+By default, caller-facing output stays masked. If the model responds with a
+placeholder produced from this request, such as `<PERSON_1>` or `<EMAIL_1>`,
+the wrapper returns the placeholder to your app and stores masked telemetry.
+If an internal route intentionally needs the previous placeholder round-trip
+behavior, opt in explicitly:
+
+```ts
+const secured = agent.wrapOpenAI(openai, {
+  system_id: process.env.AGENTID_SYSTEM_ID!,
+  deanonymizeOutputForClient: true,
+});
+```
+
+Do not enable this for data-minimization deployments unless the application is
+allowed to receive the original values back in the model response path.
+
 Important: this applies only to the wrapped call. If your app sends raw prompt
 or raw chat history through a separate direct provider call, AgentID cannot
 protect that bypass.
@@ -163,11 +179,33 @@ For chat apps and agent workflows, protect the full message history, not just
 the latest text field. If a previous user/assistant/tool/memory message contains
 raw PII, the model can still repeat it later.
 
+Current wrapper scope note: `wrapOpenAI()` can protect full message history for
+provider dispatch when SDK-side masking is enabled, but its preflight `guard()`
+input is currently derived from the last user message text plus supported inline
+attachments on that last user turn. If you need preflight evaluation over the
+exact assembled multi-turn history today, use an explicit manual
+`guard -> provider -> log` flow for that route.
+
 If you cannot use `wrapOpenAI()` and need a manual integration, call
 `protectMessageHistory()` on the exact history that will be sent to the
 provider. Then pass `protected.messages` to the provider, not the raw
 `body.messages`.
 
+If your app uses Vercel AI SDK React `useChat()`, prefer
+`agentid-vercel-sdk/react` and `useAgentIdChat()` instead of rebuilding
+transport preparation in generic Node code.
+
+Treat one provider call as one protected unit of work:
+
+1. Build the exact `messages` array for this model call.
+2. Run `protectMessageHistory()` once on that full array.
+3. Call `guard()` once for that same model call.
+4. Send `protectedHistory.messages` to the provider.
+
+Do not loop over historical messages and call `guard()` once per prior turn.
+That creates multiple guard events for one LLM call and can look like duplicated
+or stale conversation logging.
+
 ```ts
 import { AgentID, protectMessageHistory } from "agentid-sdk";
 
@@ -204,9 +242,52 @@ const response = await openai.chat.completions.create({
 });
 ```
 
+For non-Vercel chat UIs, use `protectChatState()` when you want one helper to
+produce separate views for UI rendering, provider dispatch, and persistence:
+
+```ts
+import { protectChatState } from "agentid-sdk";
+
+const protectedChat = protectChatState(messages, {
+  transcript: {
+    ui: "masked",
+    provider: "masked",
+    persistence: "masked",
+  },
+});
+
+renderMessages(protectedChat.uiMessages);
+await provider.chat.completions.create({
+  model: "gpt-4o-mini",
+  messages: protectedChat.providerMessages,
+});
+await saveTranscript(protectedChat.persistenceMessages);
+```
+
+If your product intentionally shows the user's raw prompt locally, make that
+explicit while keeping provider and persistence protected:
+
+```ts
+const protectedChat = protectChatState(messages, {
+  transcript: { ui: "raw", provider: "masked", persistence: "masked" },
+});
+```
+
+The returned placeholder mapping is local to your process/session. Do not
+persist it unless you have an explicit encrypted vault design.
+
 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.
+> 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.
+>
+> Enterprise rollout rule: the main production risk is not usually a weak classifier. It is an unwrapped provider call or helper that sends prompt/history outside `wrapOpenAI()`, LangChain callbacks, or an explicit `guard -> provider -> log` path. If your app also uses `responses.create`, Assistants, custom fetches, or a second raw OpenAI client, those paths must be integrated separately or treated as coverage gaps.
+
+Before calling an integration enterprise-ready, verify all of these:
+
+1. Every production LLM callsite uses `wrapOpenAI()`, a LangChain callback-wrapped model, or an explicit manual `guard -> provider -> log` flow.
+2. No parallel raw provider call exists in the same request path.
+3. Chat and agent routes protect the full message history sent to the provider, not just the latest user text.
+4. Manual integrations set `full_history_protected=true` only when the exact provider payload was protected before dispatch.
 
 ### Vercel AI SDK Wrapper
 

package/dist/{agentid-BWlN5KCq.d.mts → agentid-DbTWrLnN.d.mts}

@@ -42,6 +42,7 @@ interface GuardAttachment {
 }
 interface GuardParams {
     input: string;
+    prompt_context?: string;
     system_id: string;
     model?: string;
     user_id?: string;
@@ -54,6 +55,7 @@ interface GuardParams {
         capabilities: {
             has_feedback_handler: boolean;
             pii_masking_enabled: boolean;
+            secret_masking_enabled?: boolean;
             framework: string;
         };
     };
@@ -126,6 +128,7 @@ type AgentEventType = "start" | "complete" | "error" | "human_override" | "secur
 type InjectionScanRequestOptions = RequestOptions & {
     clientEventId?: string;
     systemId?: string;
+    attachments?: GuardAttachment[];
 };
 type PromptPreflightLogParams = {
     system_id: string;
@@ -153,6 +156,13 @@ interface WrapOpenAIOptions {
     apiKey?: string;
     api_key?: string;
     resolveApiKey?: (request: Record<string, unknown>) => string | undefined;
+    /**
+     * Opt-in legacy behavior: if the model returns AgentID placeholders that were
+     * produced from this request's input, restore them before returning to the
+     * application caller. Defaults to false so caller-facing output stays masked.
+     */
+    deanonymizeOutputForClient?: boolean;
+    deanonymize_output_for_client?: boolean;
 }
 interface LogParams {
     event_id?: string;
@@ -220,6 +230,7 @@ interface OperationLogParams {
         capabilities: {
             has_feedback_handler: boolean;
             pii_masking_enabled: boolean;
+            secret_masking_enabled?: boolean;
             framework: string;
         };
     };
@@ -263,6 +274,7 @@ declare class AgentID {
     private localEnforcer;
     private injectionScanner;
     private recentGuardVerdicts;
+    private pendingGuardRequests;
     constructor(config?: AgentIDConfig);
     get piiMasking(): boolean | undefined;
     get secretMasking(): boolean | undefined;
@@ -284,10 +296,13 @@ declare class AgentID {
     private buildFailOpenGuardVerdict;
     private maybeRaiseStrictIngestDependencyError;
     private shouldRunLocalInjectionScan;
+    private buildInlineAttachmentPromptScanInput;
+    private buildPromptInjectionScanInput;
     private refreshCapabilityConfigBeforeClientControl;
     private applyLocalPolicyChecks;
     prepareInputForDispatch(params: {
         input: string;
+        promptContext?: string;
         systemId: string;
         stream: boolean;
         skipInjectionScan?: boolean;
@@ -296,6 +311,7 @@ declare class AgentID {
     }, options?: RequestOptions): Promise<PreparedInput>;
     applyLocalFallbackForGuardFailure(params: {
         input: string;
+        promptContext?: string;
         systemId: string;
         stream: boolean;
         clientEventId?: string;
@@ -303,6 +319,20 @@ declare class AgentID {
         sdkConfigFetchMs?: number;
         telemetryMetadata?: AgentTelemetryContext;
     }, options?: RequestOptions): Promise<PreparedInput>;
+    runLocalPromptInjectionFallback(params: {
+        input: string;
+        promptContext?: string;
+        attachments?: GuardAttachment[];
+        systemId?: string;
+        clientEventId?: string;
+        capabilityConfig?: CapabilityConfig;
+        sdkConfigFetchMs?: number;
+        telemetryMetadata?: AgentTelemetryContext;
+    }, options?: RequestOptions): Promise<{
+        capabilityConfig: CapabilityConfig;
+        sdkConfigFetchMs: number;
+        sdkLocalScanMs: number;
+    }>;
     scanPromptInjection(input: string, options?: InjectionScanRequestOptions): Promise<void>;
     private withMaskedOpenAIRequest;
     private logSecurityPolicyViolation;

package/dist/{agentid-BWlN5KCq.d.ts → agentid-DbTWrLnN.d.ts}

@@ -42,6 +42,7 @@ interface GuardAttachment {
 }
 interface GuardParams {
     input: string;
+    prompt_context?: string;
     system_id: string;
     model?: string;
     user_id?: string;
@@ -54,6 +55,7 @@ interface GuardParams {
         capabilities: {
             has_feedback_handler: boolean;
             pii_masking_enabled: boolean;
+            secret_masking_enabled?: boolean;
             framework: string;
         };
     };
@@ -126,6 +128,7 @@ type AgentEventType = "start" | "complete" | "error" | "human_override" | "secur
 type InjectionScanRequestOptions = RequestOptions & {
     clientEventId?: string;
     systemId?: string;
+    attachments?: GuardAttachment[];
 };
 type PromptPreflightLogParams = {
     system_id: string;
@@ -153,6 +156,13 @@ interface WrapOpenAIOptions {
     apiKey?: string;
     api_key?: string;
     resolveApiKey?: (request: Record<string, unknown>) => string | undefined;
+    /**
+     * Opt-in legacy behavior: if the model returns AgentID placeholders that were
+     * produced from this request's input, restore them before returning to the
+     * application caller. Defaults to false so caller-facing output stays masked.
+     */
+    deanonymizeOutputForClient?: boolean;
+    deanonymize_output_for_client?: boolean;
 }
 interface LogParams {
     event_id?: string;
@@ -220,6 +230,7 @@ interface OperationLogParams {
         capabilities: {
             has_feedback_handler: boolean;
             pii_masking_enabled: boolean;
+            secret_masking_enabled?: boolean;
             framework: string;
         };
     };
@@ -263,6 +274,7 @@ declare class AgentID {
     private localEnforcer;
     private injectionScanner;
     private recentGuardVerdicts;
+    private pendingGuardRequests;
     constructor(config?: AgentIDConfig);
     get piiMasking(): boolean | undefined;
     get secretMasking(): boolean | undefined;
@@ -284,10 +296,13 @@ declare class AgentID {
     private buildFailOpenGuardVerdict;
     private maybeRaiseStrictIngestDependencyError;
     private shouldRunLocalInjectionScan;
+    private buildInlineAttachmentPromptScanInput;
+    private buildPromptInjectionScanInput;
     private refreshCapabilityConfigBeforeClientControl;
     private applyLocalPolicyChecks;
     prepareInputForDispatch(params: {
         input: string;
+        promptContext?: string;
         systemId: string;
         stream: boolean;
         skipInjectionScan?: boolean;
@@ -296,6 +311,7 @@ declare class AgentID {
     }, options?: RequestOptions): Promise<PreparedInput>;
     applyLocalFallbackForGuardFailure(params: {
         input: string;
+        promptContext?: string;
         systemId: string;
         stream: boolean;
         clientEventId?: string;
@@ -303,6 +319,20 @@ declare class AgentID {
         sdkConfigFetchMs?: number;
         telemetryMetadata?: AgentTelemetryContext;
     }, options?: RequestOptions): Promise<PreparedInput>;
+    runLocalPromptInjectionFallback(params: {
+        input: string;
+        promptContext?: string;
+        attachments?: GuardAttachment[];
+        systemId?: string;
+        clientEventId?: string;
+        capabilityConfig?: CapabilityConfig;
+        sdkConfigFetchMs?: number;
+        telemetryMetadata?: AgentTelemetryContext;
+    }, options?: RequestOptions): Promise<{
+        capabilityConfig: CapabilityConfig;
+        sdkConfigFetchMs: number;
+        sdkLocalScanMs: number;
+    }>;
     scanPromptInjection(input: string, options?: InjectionScanRequestOptions): Promise<void>;
     private withMaskedOpenAIRequest;
     private logSecurityPolicyViolation;