agentid-sdk 0.1.36 → 0.1.38

package/dist/agentid-CxVUF_eo.d.ts

@@ -0,0 +1,399 @@
+type PIIMapping = Record<string, string>;
+type PIIAnonymizeOptions = {
+    pii?: boolean;
+    secrets?: boolean;
+};
+declare class PIIManager {
+    /**
+     * Reversible local-first masking using <TYPE_INDEX> placeholders.
+     *
+     * Zero-dependency fallback with strict checksum validation for CEE national IDs.
+     */
+    anonymize(text: string, options?: PIIAnonymizeOptions): {
+        maskedText: string;
+        mapping: PIIMapping;
+    };
+    deanonymize(text: string, mapping: PIIMapping): string;
+}
+
+type CapabilityConfig = {
+    version?: number | null;
+    shadow_mode: boolean;
+    strict_security_mode: boolean;
+    failure_mode: "fail_open" | "fail_close";
+    block_on_heuristic: boolean;
+    inject_transparency_metadata: boolean;
+    block_pii_leakage: boolean;
+    enable_sdk_pii_masking?: boolean;
+    block_secret_leakage?: boolean;
+    enable_sdk_secret_masking?: boolean;
+    block_db_access: boolean;
+    block_code_execution: boolean;
+    block_toxicity: boolean;
+};
+
+interface GuardAttachment {
+    filename: string;
+    mime_type?: string;
+    mimeType?: string;
+    content_base64?: string;
+    contentBase64?: string;
+    text?: string;
+}
+interface GuardParams {
+    input: string;
+    system_id: string;
+    model?: string;
+    user_id?: string;
+    client_event_id?: string;
+    expected_languages?: string[];
+    request_identity?: Record<string, unknown>;
+    metadata?: AgentTelemetryContext;
+    attachments?: GuardAttachment[];
+    client_capabilities?: {
+        capabilities: {
+            has_feedback_handler: boolean;
+            pii_masking_enabled: boolean;
+            framework: string;
+        };
+    };
+}
+interface GuardResponse {
+    allowed: boolean;
+    reason?: string;
+    detected_pii?: boolean;
+    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" | "auto_detected" | "global_high_priority" | "core_en_fallback";
+    policy_pack_scan_mode?: "full" | "segmented";
+    exotic_language_detected?: boolean;
+    langid_primary?: string;
+    langid_confidence?: "high" | "medium" | "low";
+    langid_secondary?: string[];
+    langid_mixed?: boolean;
+    langid_source?: "input_detection" | "input_detection_with_hint";
+    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;
+}
+type AgentTelemetryContext = {
+    workflow_id?: string;
+    workflow_run_id?: string;
+    workflow_step_id?: string;
+    workflow_name?: string;
+    workflow_step_name?: string;
+    workflow_step_index?: number;
+    parent_event_id?: string;
+    tool_name?: string;
+    tool_target?: string;
+    tool_target_type?: string;
+    event_title?: string;
+    event_status?: string;
+    event_category?: string;
+    event_subtype?: string;
+    workflowId?: string;
+    workflowRunId?: string;
+    workflowStepId?: string;
+    workflowName?: string;
+    workflowStepName?: string;
+    workflowStepIndex?: number;
+    parentEventId?: string;
+    toolName?: string;
+    toolTarget?: string;
+    toolTargetType?: string;
+    eventTitle?: string;
+    eventStatus?: string;
+    eventCategory?: string;
+    eventSubtype?: string;
+    [key: string]: unknown;
+};
+type AgentOperationCategory = "ai" | "guard" | "tool" | "delivery" | "inbox" | "workflow" | "compliance" | "operational";
+type AgentOperationStatus = "started" | "completed" | "failed" | "blocked" | "skipped";
+type AgentEventType = "start" | "complete" | "error" | "human_override" | "security_alert" | "security_block" | "security_policy_violation" | "transparency_badge_rendered" | (string & {});
+type InjectionScanRequestOptions = RequestOptions & {
+    clientEventId?: string;
+    systemId?: string;
+};
+type PromptPreflightLogParams = {
+    system_id: string;
+    user_id?: string;
+    request_identity?: Record<string, unknown>;
+    model?: string;
+    input: string;
+    telemetry?: AgentTelemetryContext;
+    guard_event_id?: string | null;
+    guard_latency_ms?: number | null;
+    preflight_for_client_event_id: string;
+    verdict: Pick<GuardResponse, "allowed" | "reason" | "detected_pii" | "shadow_mode" | "simulated_decision" | "shadow_blocked">;
+    client_capabilities?: LogParams["client_capabilities"];
+    local_fallback_applied?: boolean;
+    local_fallback_reason?: string | null;
+    runtime_surface?: string;
+};
+interface WrapOpenAIOptions {
+    system_id: string;
+    user_id?: string;
+    expected_languages?: string[];
+    expectedLanguages?: string[];
+    request_identity?: Record<string, unknown>;
+    telemetry?: AgentTelemetryContext;
+    apiKey?: string;
+    api_key?: string;
+    resolveApiKey?: (request: Record<string, unknown>) => string | undefined;
+}
+interface LogParams {
+    event_id?: string;
+    system_id?: string;
+    input: string;
+    output: string;
+    model: string;
+    usage?: Record<string, unknown>;
+    tokens?: Record<string, unknown>;
+    latency?: number;
+    user_id?: string;
+    request_identity?: Record<string, unknown>;
+    metadata?: Record<string, unknown>;
+    event_type?: AgentEventType;
+    severity?: "info" | "warning" | "error" | "high";
+    timestamp?: string;
+    client_capabilities?: {
+        capabilities: {
+            has_feedback_handler: boolean;
+            pii_masking_enabled: boolean;
+            framework: string;
+        };
+    };
+}
+type AgentIDConfig = {
+    apiKey?: string;
+    baseUrl?: string;
+    piiMasking?: boolean;
+    secretMasking?: boolean;
+    checkInjection?: boolean;
+    clientFastFail?: boolean;
+    client_fast_fail?: boolean;
+    aiScanEnabled?: boolean;
+    storePii?: boolean;
+    strictMode?: boolean;
+    failureMode?: "fail_open" | "fail_close";
+    guardTimeoutMs?: number;
+    ingestTimeoutMs?: number;
+};
+
+declare function createAgentIdCorrelationId(seed?: string): string;
+declare function createAgentIdTelemetryContext(value?: AgentTelemetryContext): AgentTelemetryContext | undefined;
+declare function createAgentIdOperationLog(params: OperationLogParams): LogParams;
+interface OperationLogParams {
+    event_id?: string;
+    client_event_id?: string;
+    system_id?: string;
+    user_id?: string;
+    request_identity?: Record<string, unknown>;
+    input?: string;
+    output?: string;
+    model?: string;
+    usage?: Record<string, unknown>;
+    tokens?: Record<string, unknown>;
+    latency?: number;
+    metadata?: Record<string, unknown>;
+    telemetry?: AgentTelemetryContext;
+    event_type?: AgentEventType;
+    event_category?: AgentOperationCategory | string;
+    event_subtype?: string;
+    event_status?: AgentOperationStatus | string;
+    severity?: "info" | "warning" | "error" | "high";
+    timestamp?: string;
+    client_capabilities?: {
+        capabilities: {
+            has_feedback_handler: boolean;
+            pii_masking_enabled: boolean;
+            framework: string;
+        };
+    };
+}
+type PreparedInput = {
+    sanitizedInput: string;
+    capabilityConfig: CapabilityConfig;
+    sdkConfigFetchMs?: number;
+    sdkLocalScanMs?: number;
+    piiMapping?: PIIMapping;
+    shouldDeanonymize?: boolean;
+};
+declare class SecurityBlockError extends Error {
+    reason: string;
+    constructor(reason?: string);
+}
+declare class DependencyError extends Error {
+    dependency: "ingest";
+    reason: string;
+    status: number | null;
+    constructor(params: {
+        dependency: "ingest";
+        reason: string;
+        status: number | null;
+    });
+}
+declare class AgentID {
+    private baseUrl;
+    private apiKey;
+    private configuredPiiMasking;
+    private configuredSecretMasking;
+    private checkInjection;
+    private clientFastFail;
+    private aiScanEnabled;
+    private storePii;
+    private strictMode;
+    private configuredFailureMode;
+    private guardTimeoutMs;
+    private ingestTimeoutMs;
+    private pii;
+    private localEnforcer;
+    private injectionScanner;
+    private recentGuardVerdicts;
+    constructor(config?: AgentIDConfig);
+    get piiMasking(): boolean | undefined;
+    get secretMasking(): boolean | undefined;
+    private resolveEffectivePiiMasking;
+    private resolveEffectiveSecretMasking;
+    getEffectivePiiMasking(options?: RequestOptions): boolean;
+    getEffectivePiiMaskingForConfig(capabilityConfig?: CapabilityConfig): boolean;
+    getEffectiveSecretMaskingForConfig(capabilityConfig?: CapabilityConfig): boolean;
+    private buildClientCapabilities;
+    private resolveApiKey;
+    private resolveClientEventId;
+    private buildGuardCacheKey;
+    private readCachedGuardVerdict;
+    private cacheGuardVerdict;
+    getCapabilityConfig(force?: boolean, options?: RequestOptions): Promise<CapabilityConfig>;
+    private getCapabilityConfigWithTelemetry;
+    private getCachedCapabilityConfig;
+    private resolveEffectiveStrictMode;
+    private maybeRaiseStrictIngestDependencyError;
+    private shouldRunLocalInjectionScan;
+    private refreshCapabilityConfigBeforeClientControl;
+    private applyLocalPolicyChecks;
+    prepareInputForDispatch(params: {
+        input: string;
+        systemId: string;
+        stream: boolean;
+        skipInjectionScan?: boolean;
+        clientEventId?: string;
+        telemetryMetadata?: AgentTelemetryContext;
+    }, options?: RequestOptions): Promise<PreparedInput>;
+    applyLocalFallbackForGuardFailure(params: {
+        input: string;
+        systemId: string;
+        stream: boolean;
+        clientEventId?: string;
+        capabilityConfig?: CapabilityConfig;
+        sdkConfigFetchMs?: number;
+        telemetryMetadata?: AgentTelemetryContext;
+    }, 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.
+     * strictMode=true: FAIL-CLOSED and throws on connectivity/timeouts.
+     */
+    guard(params: GuardParams, options?: RequestOptions): Promise<GuardResponse>;
+    private sendIngest;
+    private extractStreamChunkText;
+    private extractStreamChunkUsage;
+    private isOpenAIStreamFinishChunk;
+    private setOpenAIStreamChunkText;
+    private createSyntheticOpenAIStreamChunk;
+    private rewriteOpenAIStreamChunkForClient;
+    private wrapCompletion;
+    /**
+     * LOG: Sends telemetry after execution.
+     * Returns a Promise so callers can await persistence when needed.
+     */
+    log(params: LogParams, options?: RequestOptions): Promise<void>;
+    buildOperationLogParams(params: OperationLogParams): LogParams;
+    logOperation(params: OperationLogParams, options?: RequestOptions): Promise<void>;
+    logPromptPreflightStep(params: PromptPreflightLogParams, options?: RequestOptions): Promise<void>;
+    operation(params: OperationLogParams, options?: RequestOptions): Promise<void>;
+    /**
+     * Analytics alias for telemetry logging.
+     */
+    analytics(params: LogParams, options?: RequestOptions): Promise<void>;
+    /**
+     * Trace alias for telemetry logging.
+     */
+    trace(params: LogParams, options?: RequestOptions): Promise<void>;
+    /**
+     * Wrap an OpenAI client once; AgentID will automatically:
+     * - run guard() before chat.completions.create
+     * - measure latency
+     * - persist ingest telemetry for the wrapped call
+     */
+    wrapOpenAI<T>(openai: T, options: WrapOpenAIOptions): T;
+}
+type AgentIDWorkflowTrailAgent = Pick<AgentID, "buildOperationLogParams" | "log">;
+interface AgentIDWorkflowTrailOptions {
+    agent: AgentIDWorkflowTrailAgent;
+    system_id: string;
+    user_id?: string;
+    request_identity?: Record<string, unknown>;
+    telemetry?: AgentTelemetryContext;
+    client_capabilities?: LogParams["client_capabilities"];
+    requestOptions?: RequestOptions;
+}
+type AgentIDWorkflowStepParams = Omit<OperationLogParams, "system_id" | "user_id" | "request_identity">;
+interface AgentIDWorkflowRunHooks<TResult = unknown> {
+    complete?: AgentIDWorkflowStepParams;
+    fail?: AgentIDWorkflowStepParams;
+    onComplete?: (result: TResult) => AgentIDWorkflowStepParams | void;
+    onError?: (error: unknown) => AgentIDWorkflowStepParams | void;
+}
+declare class AgentIDWorkflowStep {
+    readonly workflowStepId: string;
+    readonly startEventId: string;
+    readonly telemetry?: AgentTelemetryContext;
+    private trail;
+    private startedAtMs;
+    constructor(params: {
+        trail: AgentIDWorkflowTrail;
+        workflowStepId: string;
+        startEventId: string;
+        telemetry?: AgentTelemetryContext;
+        startedAtMs: number;
+    });
+    private resolveStepTelemetry;
+    log(params?: AgentIDWorkflowStepParams, options?: RequestOptions): Promise<LogParams>;
+    complete(params?: AgentIDWorkflowStepParams, options?: RequestOptions): Promise<LogParams>;
+    fail(error: unknown, params?: AgentIDWorkflowStepParams, options?: RequestOptions): Promise<LogParams>;
+}
+declare class AgentIDWorkflowTrail {
+    private agent;
+    private systemId;
+    private userId?;
+    private requestIdentity?;
+    private telemetry?;
+    private clientCapabilities?;
+    private requestOptions?;
+    constructor(options: AgentIDWorkflowTrailOptions);
+    logStep(params?: AgentIDWorkflowStepParams, options?: RequestOptions): Promise<LogParams>;
+    startStep(params?: AgentIDWorkflowStepParams, options?: RequestOptions): Promise<AgentIDWorkflowStep>;
+    runStep<TResult>(params: AgentIDWorkflowStepParams, run: () => Promise<TResult> | TResult, hooks?: AgentIDWorkflowRunHooks<TResult>, options?: RequestOptions): Promise<TResult>;
+}
+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 };