agentid-sdk 0.1.38 → 0.1.41

package/README.md

@@ -111,6 +111,10 @@ console.log(response.choices[0]?.message?.content ?? "");
 By default, official AgentID SDK integrations inherit `enable_sdk_pii_masking`
 from the dashboard/runtime config. You only need to set `piiMasking: true` in
 code if you want to force local masking on even when the dashboard policy is off.
+Starting with `agentid-sdk@0.1.40`, fail-open dependency fallback keeps local
+deterministic PII and secret masking enabled when `/agent/config` or `/guard`
+is unreachable. Fail-open can preserve availability, but official wrappers must
+not treat it as permission to send raw sensitive text to the provider.
 
 When SDK-side masking is enabled, the wrapper now masks both classic PII and
 high-confidence secret material before the request leaves your process:
@@ -121,10 +125,86 @@ high-confidence secret material before the request leaves your process:
 - password / credential assignments, PEM private keys, Azure connection strings and SAS tokens
 
 The masked form is what gets sent to `/guard`, logged to AgentID ingest, and
-forwarded to the model provider. Placeholder mapping stays local to the SDK and
-can be deanonymized back to the caller after completion.
-
-Wrapped OpenAI calls persist telemetry for both regular and streamed completions. For `stream: true`, logging happens when the stream finishes.
+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.
+
+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.
+
+Correct:
+
+```ts
+const secured = agent.wrapOpenAI(openai, {
+  system_id: process.env.AGENTID_SYSTEM_ID!,
+});
+
+await secured.chat.completions.create({
+  model: "gpt-4o-mini",
+  messages: fullConversationHistory,
+});
+```
+
+Incorrect:
+
+```ts
+// Raw history reaches the provider.
+await openai.chat.completions.create({
+  model: "gpt-4o-mini",
+  messages: rawConversationHistory,
+});
+
+// Logging a masked copy later does not protect the model call above.
+await agent.log({ system_id: systemId, input: maskedInput, output: maskedOutput });
+```
+
+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.
+
+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`.
+
+```ts
+import { AgentID, protectMessageHistory } from "agentid-sdk";
+
+const agent = new AgentID();
+const protectedHistory = protectMessageHistory(body.messages, {
+  pii: true,
+  secrets: true,
+});
+
+const latestUserInput = extractLatestUserInput(protectedHistory.messages);
+const verdict = await agent.guard({
+  system_id: process.env.AGENTID_SYSTEM_ID!,
+  input: latestUserInput,
+  model: "gpt-4o-mini",
+  metadata: {
+    runtime_surface: "manual_provider_integration",
+    full_history_protected: true,
+    messages_count: Array.isArray(protectedHistory.messages)
+      ? protectedHistory.messages.length
+      : undefined,
+    protected_messages_count: Array.isArray(protectedHistory.messages)
+      ? protectedHistory.messages.length
+      : undefined,
+    prompt_text_parts_count: protectedHistory.textPartsCount,
+    transformed_prompt_text_parts_count:
+      protectedHistory.transformedTextPartsCount,
+  },
+});
+if (!verdict.allowed) throw new Error(`Blocked: ${verdict.reason}`);
+
+const response = await openai.chat.completions.create({
+  model: "gpt-4o-mini",
+  messages: protectedHistory.messages,
+});
+```
+
+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.
 
@@ -198,17 +278,28 @@ import { AgentID } from "agentid-sdk";
 
 const agent = new AgentID();
 
-await agent.log({
-  system_id: process.env.AGENTID_SYSTEM_ID!,
-  event_type: "complete",
-  severity: "info",
-  model: "gpt-4o-mini",
-  input: "Raw telemetry prompt",
-  output: '{"ok": true}',
+await agent.log({
+  system_id: process.env.AGENTID_SYSTEM_ID!,
+  event_type: "complete",
+  severity: "info",
+  model: "gpt-4o-mini",
+  input: "Raw telemetry prompt",
+  output: '{"ok": true}',
+  usage: {
+    prompt_tokens: 33,
+    completion_tokens: 9,
+    total_tokens: 42,
+  },
+  latency: 1450,
   metadata: { agent_role: "batch-worker", channel: "manual_ingest" },
 });
 ```
 
+For manual integrations, preserve provider usage. Without `usage` or
+normalized `tokens`, AgentID can store Activity but cannot compute token totals,
+`cost_usd`, Total Spend, or ROI. ROI also requires the system business context
+fields `human_hourly_rate` and `human_time_per_task_min`.
+
 ### Agent workflow and tool events
 
 Use `logOperation()` when an agent calls tools or performs operational work outside the wrapped LLM call. Reuse the same `workflowRunId` across steps.

package/dist/{agentid-CxVUF_eo.d.mts → agentid-Mjh8rXn0.d.mts}

@@ -263,6 +263,7 @@ declare class AgentID {
     private localEnforcer;
     private injectionScanner;
     private recentGuardVerdicts;
+    private pendingGuardRequests;
     constructor(config?: AgentIDConfig);
     get piiMasking(): boolean | undefined;
     get secretMasking(): boolean | undefined;
@@ -281,6 +282,7 @@ declare class AgentID {
     private getCapabilityConfigWithTelemetry;
     private getCachedCapabilityConfig;
     private resolveEffectiveStrictMode;
+    private buildFailOpenGuardVerdict;
     private maybeRaiseStrictIngestDependencyError;
     private shouldRunLocalInjectionScan;
     private refreshCapabilityConfigBeforeClientControl;
@@ -396,4 +398,4 @@ declare class AgentIDWorkflowTrail {
 }
 declare function createAgentIdWorkflowTrail(options: AgentIDWorkflowTrailOptions): AgentIDWorkflowTrail;
 
-export { type AgentEventType as A, DependencyError as D, type GuardAttachment as G, type LogParams as L, type OperationLogParams as O, PIIManager as P, type RequestOptions as R, SecurityBlockError as S, type TransparencyMetadata as T, type WrapOpenAIOptions as W, AgentID as a, type AgentIDWorkflowRunHooks as b, AgentIDWorkflowStep as c, type AgentIDWorkflowStepParams as d, AgentIDWorkflowTrail as e, type AgentIDWorkflowTrailOptions as f, type AgentOperationCategory as g, type AgentOperationStatus as h, type AgentTelemetryContext as i, type GuardParams as j, type GuardResponse as k, type PIIAnonymizeOptions as l, type PIIMapping as m, type PreparedInput as n, createAgentIdCorrelationId as o, createAgentIdOperationLog as p, createAgentIdTelemetryContext as q, createAgentIdWorkflowTrail as r };
+export { type AgentEventType as A, DependencyError as D, type GuardAttachment as G, type LogParams as L, type OperationLogParams as O, type PIIAnonymizeOptions as P, type RequestOptions as R, SecurityBlockError as S, type TransparencyMetadata as T, type WrapOpenAIOptions as W, PIIManager as a, AgentID as b, type AgentIDWorkflowRunHooks as c, AgentIDWorkflowStep as d, type AgentIDWorkflowStepParams as e, AgentIDWorkflowTrail as f, type AgentIDWorkflowTrailOptions as g, type AgentOperationCategory as h, type AgentOperationStatus as i, type AgentTelemetryContext as j, type GuardParams as k, type GuardResponse as l, type PIIMapping as m, type PreparedInput as n, createAgentIdCorrelationId as o, createAgentIdOperationLog as p, createAgentIdTelemetryContext as q, createAgentIdWorkflowTrail as r };

package/dist/{agentid-CxVUF_eo.d.ts → agentid-Mjh8rXn0.d.ts}

@@ -263,6 +263,7 @@ declare class AgentID {
     private localEnforcer;
     private injectionScanner;
     private recentGuardVerdicts;
+    private pendingGuardRequests;
     constructor(config?: AgentIDConfig);
     get piiMasking(): boolean | undefined;
     get secretMasking(): boolean | undefined;
@@ -281,6 +282,7 @@ declare class AgentID {
     private getCapabilityConfigWithTelemetry;
     private getCachedCapabilityConfig;
     private resolveEffectiveStrictMode;
+    private buildFailOpenGuardVerdict;
     private maybeRaiseStrictIngestDependencyError;
     private shouldRunLocalInjectionScan;
     private refreshCapabilityConfigBeforeClientControl;
@@ -396,4 +398,4 @@ declare class AgentIDWorkflowTrail {
 }
 declare function createAgentIdWorkflowTrail(options: AgentIDWorkflowTrailOptions): AgentIDWorkflowTrail;
 
-export { type AgentEventType as A, DependencyError as D, type GuardAttachment as G, type LogParams as L, type OperationLogParams as O, PIIManager as P, type RequestOptions as R, SecurityBlockError as S, type TransparencyMetadata as T, type WrapOpenAIOptions as W, AgentID as a, type AgentIDWorkflowRunHooks as b, AgentIDWorkflowStep as c, type AgentIDWorkflowStepParams as d, AgentIDWorkflowTrail as e, type AgentIDWorkflowTrailOptions as f, type AgentOperationCategory as g, type AgentOperationStatus as h, type AgentTelemetryContext as i, type GuardParams as j, type GuardResponse as k, type PIIAnonymizeOptions as l, type PIIMapping as m, type PreparedInput as n, createAgentIdCorrelationId as o, createAgentIdOperationLog as p, createAgentIdTelemetryContext as q, createAgentIdWorkflowTrail as r };
+export { type AgentEventType as A, DependencyError as D, type GuardAttachment as G, type LogParams as L, type OperationLogParams as O, type PIIAnonymizeOptions as P, type RequestOptions as R, SecurityBlockError as S, type TransparencyMetadata as T, type WrapOpenAIOptions as W, PIIManager as a, AgentID as b, type AgentIDWorkflowRunHooks as c, AgentIDWorkflowStep as d, type AgentIDWorkflowStepParams as e, AgentIDWorkflowTrail as f, type AgentIDWorkflowTrailOptions as g, type AgentOperationCategory as h, type AgentOperationStatus as i, type AgentTelemetryContext as j, type GuardParams as k, type GuardResponse as l, type PIIMapping as m, type PreparedInput as n, createAgentIdCorrelationId as o, createAgentIdOperationLog as p, createAgentIdTelemetryContext as q, createAgentIdWorkflowTrail as r };