@llm-dev-ops/agentics-cli 1.4.26 → 1.4.29

package/dist/bundled-agents/governance-dashboard-agents/dist/contracts/usage-oversight.d.ts

@@ -0,0 +1,1471 @@
+/**
+ * Usage Oversight Agent Contract
+ *
+ * Classification: OVERSIGHT / VISIBILITY
+ *
+ * Purpose:
+ * Provide visibility into LLM usage patterns for governance and compliance monitoring.
+ *
+ * This agent:
+ * - Aggregates usage signals across systems
+ * - Identifies out-of-policy usage patterns
+ * - Produces oversight dashboards and signals
+ *
+ * This agent MUST NOT:
+ * - Intercept execution
+ * - Trigger retries or workflows
+ * - Enforce policies
+ * - Modify configurations
+ * - Emit anomaly detections
+ * - Apply optimizations
+ * - Connect directly to Google SQL
+ * - Execute SQL queries
+ */
+import { z } from 'zod';
+/**
+ * Usage pattern from upstream systems
+ */
+export declare const UsagePatternSchema: z.ZodObject<{
+    /** Unique identifier for the usage record */
+    usage_id: z.ZodString;
+    /** Organization context */
+    organization_id: z.ZodString;
+    /** Optional team context */
+    team_id: z.ZodOptional<z.ZodString>;
+    /** User who initiated the request */
+    user_id: z.ZodString;
+    /** LLM model used */
+    model: z.ZodString;
+    /** Provider (openai, anthropic, etc.) */
+    provider: z.ZodString;
+    /** Token counts */
+    prompt_tokens: z.ZodNumber;
+    completion_tokens: z.ZodNumber;
+    total_tokens: z.ZodNumber;
+    /** Cost in USD */
+    cost_usd: z.ZodNumber;
+    /** Latency in milliseconds */
+    latency_ms: z.ZodNumber;
+    /** Timestamp of the request */
+    timestamp: z.ZodString;
+    /** Optional metadata */
+    metadata: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+}, "strip", z.ZodTypeAny, {
+    organization_id: string;
+    timestamp: string;
+    latency_ms: number;
+    usage_id: string;
+    user_id: string;
+    model: string;
+    provider: string;
+    prompt_tokens: number;
+    completion_tokens: number;
+    total_tokens: number;
+    cost_usd: number;
+    team_id?: string | undefined;
+    metadata?: Record<string, unknown> | undefined;
+}, {
+    organization_id: string;
+    timestamp: string;
+    latency_ms: number;
+    usage_id: string;
+    user_id: string;
+    model: string;
+    provider: string;
+    prompt_tokens: number;
+    completion_tokens: number;
+    total_tokens: number;
+    cost_usd: number;
+    team_id?: string | undefined;
+    metadata?: Record<string, unknown> | undefined;
+}>;
+export type UsagePattern = z.infer<typeof UsagePatternSchema>;
+/**
+ * Policy context for usage evaluation
+ */
+export declare const PolicyContextSchema: z.ZodObject<{
+    /** Active policies for the organization */
+    active_policies: z.ZodArray<z.ZodObject<{
+        policy_id: z.ZodString;
+        policy_name: z.ZodString;
+        rules: z.ZodArray<z.ZodObject<{
+            rule_id: z.ZodString;
+            rule_type: z.ZodString;
+            threshold: z.ZodOptional<z.ZodUnknown>;
+            condition: z.ZodOptional<z.ZodString>;
+        }, "strip", z.ZodTypeAny, {
+            rule_id: string;
+            rule_type: string;
+            threshold?: unknown;
+            condition?: string | undefined;
+        }, {
+            rule_id: string;
+            rule_type: string;
+            threshold?: unknown;
+            condition?: string | undefined;
+        }>, "many">;
+    }, "strip", z.ZodTypeAny, {
+        policy_id: string;
+        policy_name: string;
+        rules: {
+            rule_id: string;
+            rule_type: string;
+            threshold?: unknown;
+            condition?: string | undefined;
+        }[];
+    }, {
+        policy_id: string;
+        policy_name: string;
+        rules: {
+            rule_id: string;
+            rule_type: string;
+            threshold?: unknown;
+            condition?: string | undefined;
+        }[];
+    }>, "many">;
+    /** Budget limits */
+    budget_limits: z.ZodOptional<z.ZodArray<z.ZodObject<{
+        budget_id: z.ZodString;
+        scope: z.ZodEnum<["organization", "team", "user"]>;
+        scope_id: z.ZodString;
+        limit_usd: z.ZodNumber;
+        current_spend_usd: z.ZodNumber;
+        period: z.ZodEnum<["daily", "weekly", "monthly"]>;
+    }, "strip", z.ZodTypeAny, {
+        budget_id: string;
+        scope: "organization" | "team" | "user";
+        scope_id: string;
+        limit_usd: number;
+        current_spend_usd: number;
+        period: "daily" | "weekly" | "monthly";
+    }, {
+        budget_id: string;
+        scope: "organization" | "team" | "user";
+        scope_id: string;
+        limit_usd: number;
+        current_spend_usd: number;
+        period: "daily" | "weekly" | "monthly";
+    }>, "many">>;
+    /** Quota limits */
+    quota_limits: z.ZodOptional<z.ZodArray<z.ZodObject<{
+        quota_id: z.ZodString;
+        scope: z.ZodEnum<["organization", "team", "user"]>;
+        scope_id: z.ZodString;
+        quota_type: z.ZodString;
+        limit_value: z.ZodNumber;
+        current_value: z.ZodNumber;
+    }, "strip", z.ZodTypeAny, {
+        scope: "organization" | "team" | "user";
+        scope_id: string;
+        quota_id: string;
+        quota_type: string;
+        limit_value: number;
+        current_value: number;
+    }, {
+        scope: "organization" | "team" | "user";
+        scope_id: string;
+        quota_id: string;
+        quota_type: string;
+        limit_value: number;
+        current_value: number;
+    }>, "many">>;
+}, "strip", z.ZodTypeAny, {
+    active_policies: {
+        policy_id: string;
+        policy_name: string;
+        rules: {
+            rule_id: string;
+            rule_type: string;
+            threshold?: unknown;
+            condition?: string | undefined;
+        }[];
+    }[];
+    budget_limits?: {
+        budget_id: string;
+        scope: "organization" | "team" | "user";
+        scope_id: string;
+        limit_usd: number;
+        current_spend_usd: number;
+        period: "daily" | "weekly" | "monthly";
+    }[] | undefined;
+    quota_limits?: {
+        scope: "organization" | "team" | "user";
+        scope_id: string;
+        quota_id: string;
+        quota_type: string;
+        limit_value: number;
+        current_value: number;
+    }[] | undefined;
+}, {
+    active_policies: {
+        policy_id: string;
+        policy_name: string;
+        rules: {
+            rule_id: string;
+            rule_type: string;
+            threshold?: unknown;
+            condition?: string | undefined;
+        }[];
+    }[];
+    budget_limits?: {
+        budget_id: string;
+        scope: "organization" | "team" | "user";
+        scope_id: string;
+        limit_usd: number;
+        current_spend_usd: number;
+        period: "daily" | "weekly" | "monthly";
+    }[] | undefined;
+    quota_limits?: {
+        scope: "organization" | "team" | "user";
+        scope_id: string;
+        quota_id: string;
+        quota_type: string;
+        limit_value: number;
+        current_value: number;
+    }[] | undefined;
+}>;
+export type PolicyContext = z.infer<typeof PolicyContextSchema>;
+/**
+ * Input schema for Usage Oversight Agent
+ */
+export declare const UsageOversightInputSchema: z.ZodObject<{
+    /** Request identifier for tracing */
+    request_id: z.ZodString;
+    /** Organization to analyze */
+    organization_id: z.ZodString;
+    /** Time range for analysis */
+    time_range: z.ZodObject<{
+        start: z.ZodString;
+        end: z.ZodString;
+    }, "strip", z.ZodTypeAny, {
+        start: string;
+        end: string;
+    }, {
+        start: string;
+        end: string;
+    }>;
+    /** Usage patterns to analyze */
+    usage_patterns: z.ZodArray<z.ZodObject<{
+        /** Unique identifier for the usage record */
+        usage_id: z.ZodString;
+        /** Organization context */
+        organization_id: z.ZodString;
+        /** Optional team context */
+        team_id: z.ZodOptional<z.ZodString>;
+        /** User who initiated the request */
+        user_id: z.ZodString;
+        /** LLM model used */
+        model: z.ZodString;
+        /** Provider (openai, anthropic, etc.) */
+        provider: z.ZodString;
+        /** Token counts */
+        prompt_tokens: z.ZodNumber;
+        completion_tokens: z.ZodNumber;
+        total_tokens: z.ZodNumber;
+        /** Cost in USD */
+        cost_usd: z.ZodNumber;
+        /** Latency in milliseconds */
+        latency_ms: z.ZodNumber;
+        /** Timestamp of the request */
+        timestamp: z.ZodString;
+        /** Optional metadata */
+        metadata: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+    }, "strip", z.ZodTypeAny, {
+        organization_id: string;
+        timestamp: string;
+        latency_ms: number;
+        usage_id: string;
+        user_id: string;
+        model: string;
+        provider: string;
+        prompt_tokens: number;
+        completion_tokens: number;
+        total_tokens: number;
+        cost_usd: number;
+        team_id?: string | undefined;
+        metadata?: Record<string, unknown> | undefined;
+    }, {
+        organization_id: string;
+        timestamp: string;
+        latency_ms: number;
+        usage_id: string;
+        user_id: string;
+        model: string;
+        provider: string;
+        prompt_tokens: number;
+        completion_tokens: number;
+        total_tokens: number;
+        cost_usd: number;
+        team_id?: string | undefined;
+        metadata?: Record<string, unknown> | undefined;
+    }>, "many">;
+    /** Policy context for evaluation */
+    policy_context: z.ZodObject<{
+        /** Active policies for the organization */
+        active_policies: z.ZodArray<z.ZodObject<{
+            policy_id: z.ZodString;
+            policy_name: z.ZodString;
+            rules: z.ZodArray<z.ZodObject<{
+                rule_id: z.ZodString;
+                rule_type: z.ZodString;
+                threshold: z.ZodOptional<z.ZodUnknown>;
+                condition: z.ZodOptional<z.ZodString>;
+            }, "strip", z.ZodTypeAny, {
+                rule_id: string;
+                rule_type: string;
+                threshold?: unknown;
+                condition?: string | undefined;
+            }, {
+                rule_id: string;
+                rule_type: string;
+                threshold?: unknown;
+                condition?: string | undefined;
+            }>, "many">;
+        }, "strip", z.ZodTypeAny, {
+            policy_id: string;
+            policy_name: string;
+            rules: {
+                rule_id: string;
+                rule_type: string;
+                threshold?: unknown;
+                condition?: string | undefined;
+            }[];
+        }, {
+            policy_id: string;
+            policy_name: string;
+            rules: {
+                rule_id: string;
+                rule_type: string;
+                threshold?: unknown;
+                condition?: string | undefined;
+            }[];
+        }>, "many">;
+        /** Budget limits */
+        budget_limits: z.ZodOptional<z.ZodArray<z.ZodObject<{
+            budget_id: z.ZodString;
+            scope: z.ZodEnum<["organization", "team", "user"]>;
+            scope_id: z.ZodString;
+            limit_usd: z.ZodNumber;
+            current_spend_usd: z.ZodNumber;
+            period: z.ZodEnum<["daily", "weekly", "monthly"]>;
+        }, "strip", z.ZodTypeAny, {
+            budget_id: string;
+            scope: "organization" | "team" | "user";
+            scope_id: string;
+            limit_usd: number;
+            current_spend_usd: number;
+            period: "daily" | "weekly" | "monthly";
+        }, {
+            budget_id: string;
+            scope: "organization" | "team" | "user";
+            scope_id: string;
+            limit_usd: number;
+            current_spend_usd: number;
+            period: "daily" | "weekly" | "monthly";
+        }>, "many">>;
+        /** Quota limits */
+        quota_limits: z.ZodOptional<z.ZodArray<z.ZodObject<{
+            quota_id: z.ZodString;
+            scope: z.ZodEnum<["organization", "team", "user"]>;
+            scope_id: z.ZodString;
+            quota_type: z.ZodString;
+            limit_value: z.ZodNumber;
+            current_value: z.ZodNumber;
+        }, "strip", z.ZodTypeAny, {
+            scope: "organization" | "team" | "user";
+            scope_id: string;
+            quota_id: string;
+            quota_type: string;
+            limit_value: number;
+            current_value: number;
+        }, {
+            scope: "organization" | "team" | "user";
+            scope_id: string;
+            quota_id: string;
+            quota_type: string;
+            limit_value: number;
+            current_value: number;
+        }>, "many">>;
+    }, "strip", z.ZodTypeAny, {
+        active_policies: {
+            policy_id: string;
+            policy_name: string;
+            rules: {
+                rule_id: string;
+                rule_type: string;
+                threshold?: unknown;
+                condition?: string | undefined;
+            }[];
+        }[];
+        budget_limits?: {
+            budget_id: string;
+            scope: "organization" | "team" | "user";
+            scope_id: string;
+            limit_usd: number;
+            current_spend_usd: number;
+            period: "daily" | "weekly" | "monthly";
+        }[] | undefined;
+        quota_limits?: {
+            scope: "organization" | "team" | "user";
+            scope_id: string;
+            quota_id: string;
+            quota_type: string;
+            limit_value: number;
+            current_value: number;
+        }[] | undefined;
+    }, {
+        active_policies: {
+            policy_id: string;
+            policy_name: string;
+            rules: {
+                rule_id: string;
+                rule_type: string;
+                threshold?: unknown;
+                condition?: string | undefined;
+            }[];
+        }[];
+        budget_limits?: {
+            budget_id: string;
+            scope: "organization" | "team" | "user";
+            scope_id: string;
+            limit_usd: number;
+            current_spend_usd: number;
+            period: "daily" | "weekly" | "monthly";
+        }[] | undefined;
+        quota_limits?: {
+            scope: "organization" | "team" | "user";
+            scope_id: string;
+            quota_id: string;
+            quota_type: string;
+            limit_value: number;
+            current_value: number;
+        }[] | undefined;
+    }>;
+    /** Optional filters */
+    filters: z.ZodOptional<z.ZodObject<{
+        team_ids: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
+        user_ids: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
+        models: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
+        providers: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
+    }, "strip", z.ZodTypeAny, {
+        team_ids?: string[] | undefined;
+        user_ids?: string[] | undefined;
+        models?: string[] | undefined;
+        providers?: string[] | undefined;
+    }, {
+        team_ids?: string[] | undefined;
+        user_ids?: string[] | undefined;
+        models?: string[] | undefined;
+        providers?: string[] | undefined;
+    }>>;
+}, "strip", z.ZodTypeAny, {
+    organization_id: string;
+    request_id: string;
+    time_range: {
+        start: string;
+        end: string;
+    };
+    usage_patterns: {
+        organization_id: string;
+        timestamp: string;
+        latency_ms: number;
+        usage_id: string;
+        user_id: string;
+        model: string;
+        provider: string;
+        prompt_tokens: number;
+        completion_tokens: number;
+        total_tokens: number;
+        cost_usd: number;
+        team_id?: string | undefined;
+        metadata?: Record<string, unknown> | undefined;
+    }[];
+    policy_context: {
+        active_policies: {
+            policy_id: string;
+            policy_name: string;
+            rules: {
+                rule_id: string;
+                rule_type: string;
+                threshold?: unknown;
+                condition?: string | undefined;
+            }[];
+        }[];
+        budget_limits?: {
+            budget_id: string;
+            scope: "organization" | "team" | "user";
+            scope_id: string;
+            limit_usd: number;
+            current_spend_usd: number;
+            period: "daily" | "weekly" | "monthly";
+        }[] | undefined;
+        quota_limits?: {
+            scope: "organization" | "team" | "user";
+            scope_id: string;
+            quota_id: string;
+            quota_type: string;
+            limit_value: number;
+            current_value: number;
+        }[] | undefined;
+    };
+    filters?: {
+        team_ids?: string[] | undefined;
+        user_ids?: string[] | undefined;
+        models?: string[] | undefined;
+        providers?: string[] | undefined;
+    } | undefined;
+}, {
+    organization_id: string;
+    request_id: string;
+    time_range: {
+        start: string;
+        end: string;
+    };
+    usage_patterns: {
+        organization_id: string;
+        timestamp: string;
+        latency_ms: number;
+        usage_id: string;
+        user_id: string;
+        model: string;
+        provider: string;
+        prompt_tokens: number;
+        completion_tokens: number;
+        total_tokens: number;
+        cost_usd: number;
+        team_id?: string | undefined;
+        metadata?: Record<string, unknown> | undefined;
+    }[];
+    policy_context: {
+        active_policies: {
+            policy_id: string;
+            policy_name: string;
+            rules: {
+                rule_id: string;
+                rule_type: string;
+                threshold?: unknown;
+                condition?: string | undefined;
+            }[];
+        }[];
+        budget_limits?: {
+            budget_id: string;
+            scope: "organization" | "team" | "user";
+            scope_id: string;
+            limit_usd: number;
+            current_spend_usd: number;
+            period: "daily" | "weekly" | "monthly";
+        }[] | undefined;
+        quota_limits?: {
+            scope: "organization" | "team" | "user";
+            scope_id: string;
+            quota_id: string;
+            quota_type: string;
+            limit_value: number;
+            current_value: number;
+        }[] | undefined;
+    };
+    filters?: {
+        team_ids?: string[] | undefined;
+        user_ids?: string[] | undefined;
+        models?: string[] | undefined;
+        providers?: string[] | undefined;
+    } | undefined;
+}>;
+export type UsageOversightInput = z.infer<typeof UsageOversightInputSchema>;
+/**
+ * Severity levels for oversight signals
+ */
+export declare const OversightSeveritySchema: z.ZodEnum<["info", "advisory", "warning", "alert"]>;
+export type OversightSeverity = z.infer<typeof OversightSeveritySchema>;
+/**
+ * Out-of-policy pattern detected
+ */
+export declare const OutOfPolicyPatternSchema: z.ZodObject<{
+    /** Pattern identifier */
+    pattern_id: z.ZodString;
+    /** Pattern category */
+    category: z.ZodEnum<["cost_anomaly", "usage_spike", "policy_threshold_breach", "quota_warning", "budget_warning", "unusual_model_usage", "off_hours_usage", "high_frequency_usage"]>;
+    /** Severity of the pattern */
+    severity: z.ZodEnum<["info", "advisory", "warning", "alert"]>;
+    /** Human-readable description */
+    description: z.ZodString;
+    /** Affected scope */
+    affected_scope: z.ZodObject<{
+        users: z.ZodArray<z.ZodString, "many">;
+        teams: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
+        models: z.ZodArray<z.ZodString, "many">;
+    }, "strip", z.ZodTypeAny, {
+        models: string[];
+        users: string[];
+        teams?: string[] | undefined;
+    }, {
+        models: string[];
+        users: string[];
+        teams?: string[] | undefined;
+    }>;
+    /** Related policy (if any) */
+    related_policy_id: z.ZodOptional<z.ZodString>;
+    /** Quantitative details */
+    metrics: z.ZodObject<{
+        observed_value: z.ZodNumber;
+        threshold_value: z.ZodOptional<z.ZodNumber>;
+        deviation_percentage: z.ZodOptional<z.ZodNumber>;
+    }, "strip", z.ZodTypeAny, {
+        observed_value: number;
+        threshold_value?: number | undefined;
+        deviation_percentage?: number | undefined;
+    }, {
+        observed_value: number;
+        threshold_value?: number | undefined;
+        deviation_percentage?: number | undefined;
+    }>;
+    /** Timeframe of the pattern */
+    timeframe: z.ZodObject<{
+        start: z.ZodString;
+        end: z.ZodString;
+    }, "strip", z.ZodTypeAny, {
+        start: string;
+        end: string;
+    }, {
+        start: string;
+        end: string;
+    }>;
+}, "strip", z.ZodTypeAny, {
+    pattern_id: string;
+    category: "cost_anomaly" | "usage_spike" | "policy_threshold_breach" | "quota_warning" | "budget_warning" | "unusual_model_usage" | "off_hours_usage" | "high_frequency_usage";
+    severity: "info" | "advisory" | "warning" | "alert";
+    description: string;
+    affected_scope: {
+        models: string[];
+        users: string[];
+        teams?: string[] | undefined;
+    };
+    metrics: {
+        observed_value: number;
+        threshold_value?: number | undefined;
+        deviation_percentage?: number | undefined;
+    };
+    timeframe: {
+        start: string;
+        end: string;
+    };
+    related_policy_id?: string | undefined;
+}, {
+    pattern_id: string;
+    category: "cost_anomaly" | "usage_spike" | "policy_threshold_breach" | "quota_warning" | "budget_warning" | "unusual_model_usage" | "off_hours_usage" | "high_frequency_usage";
+    severity: "info" | "advisory" | "warning" | "alert";
+    description: string;
+    affected_scope: {
+        models: string[];
+        users: string[];
+        teams?: string[] | undefined;
+    };
+    metrics: {
+        observed_value: number;
+        threshold_value?: number | undefined;
+        deviation_percentage?: number | undefined;
+    };
+    timeframe: {
+        start: string;
+        end: string;
+    };
+    related_policy_id?: string | undefined;
+}>;
+export type OutOfPolicyPattern = z.infer<typeof OutOfPolicyPatternSchema>;
+/**
+ * Aggregated usage summary
+ */
+export declare const UsageSummarySchema: z.ZodObject<{
+    /** Total requests in period */
+    total_requests: z.ZodNumber;
+    /** Total tokens consumed */
+    total_tokens: z.ZodNumber;
+    /** Total cost in USD */
+    total_cost_usd: z.ZodNumber;
+    /** Average latency in ms */
+    average_latency_ms: z.ZodNumber;
+    /** Unique users */
+    unique_users: z.ZodNumber;
+    /** Unique models used */
+    unique_models: z.ZodNumber;
+    /** Breakdown by model */
+    by_model: z.ZodArray<z.ZodObject<{
+        model: z.ZodString;
+        provider: z.ZodString;
+        requests: z.ZodNumber;
+        tokens: z.ZodNumber;
+        cost_usd: z.ZodNumber;
+        percentage_of_total: z.ZodNumber;
+    }, "strip", z.ZodTypeAny, {
+        model: string;
+        provider: string;
+        cost_usd: number;
+        requests: number;
+        tokens: number;
+        percentage_of_total: number;
+    }, {
+        model: string;
+        provider: string;
+        cost_usd: number;
+        requests: number;
+        tokens: number;
+        percentage_of_total: number;
+    }>, "many">;
+    /** Breakdown by user (top N) */
+    by_user: z.ZodArray<z.ZodObject<{
+        user_id: z.ZodString;
+        requests: z.ZodNumber;
+        tokens: z.ZodNumber;
+        cost_usd: z.ZodNumber;
+        percentage_of_total: z.ZodNumber;
+    }, "strip", z.ZodTypeAny, {
+        user_id: string;
+        cost_usd: number;
+        requests: number;
+        tokens: number;
+        percentage_of_total: number;
+    }, {
+        user_id: string;
+        cost_usd: number;
+        requests: number;
+        tokens: number;
+        percentage_of_total: number;
+    }>, "many">;
+    /** Temporal distribution */
+    temporal_distribution: z.ZodArray<z.ZodObject<{
+        period: z.ZodString;
+        requests: z.ZodNumber;
+        cost_usd: z.ZodNumber;
+    }, "strip", z.ZodTypeAny, {
+        cost_usd: number;
+        period: string;
+        requests: number;
+    }, {
+        cost_usd: number;
+        period: string;
+        requests: number;
+    }>, "many">;
+}, "strip", z.ZodTypeAny, {
+    total_tokens: number;
+    total_requests: number;
+    total_cost_usd: number;
+    average_latency_ms: number;
+    unique_users: number;
+    unique_models: number;
+    by_model: {
+        model: string;
+        provider: string;
+        cost_usd: number;
+        requests: number;
+        tokens: number;
+        percentage_of_total: number;
+    }[];
+    by_user: {
+        user_id: string;
+        cost_usd: number;
+        requests: number;
+        tokens: number;
+        percentage_of_total: number;
+    }[];
+    temporal_distribution: {
+        cost_usd: number;
+        period: string;
+        requests: number;
+    }[];
+}, {
+    total_tokens: number;
+    total_requests: number;
+    total_cost_usd: number;
+    average_latency_ms: number;
+    unique_users: number;
+    unique_models: number;
+    by_model: {
+        model: string;
+        provider: string;
+        cost_usd: number;
+        requests: number;
+        tokens: number;
+        percentage_of_total: number;
+    }[];
+    by_user: {
+        user_id: string;
+        cost_usd: number;
+        requests: number;
+        tokens: number;
+        percentage_of_total: number;
+    }[];
+    temporal_distribution: {
+        cost_usd: number;
+        period: string;
+        requests: number;
+    }[];
+}>;
+export type UsageSummary = z.infer<typeof UsageSummarySchema>;
+/**
+ * Policy adherence status
+ */
+export declare const PolicyAdherenceSchema: z.ZodObject<{
+    /** Policy identifier */
+    policy_id: z.ZodString;
+    /** Policy name */
+    policy_name: z.ZodString;
+    /** Overall adherence status */
+    status: z.ZodEnum<["compliant", "warning", "violation"]>;
+    /** Adherence percentage (0-100) */
+    adherence_percentage: z.ZodNumber;
+    /** Rule-level adherence */
+    rule_adherence: z.ZodArray<z.ZodObject<{
+        rule_id: z.ZodString;
+        rule_type: z.ZodString;
+        status: z.ZodEnum<["compliant", "warning", "violation"]>;
+        details: z.ZodOptional<z.ZodString>;
+    }, "strip", z.ZodTypeAny, {
+        status: "warning" | "compliant" | "violation";
+        rule_id: string;
+        rule_type: string;
+        details?: string | undefined;
+    }, {
+        status: "warning" | "compliant" | "violation";
+        rule_id: string;
+        rule_type: string;
+        details?: string | undefined;
+    }>, "many">;
+}, "strip", z.ZodTypeAny, {
+    status: "warning" | "compliant" | "violation";
+    policy_id: string;
+    policy_name: string;
+    adherence_percentage: number;
+    rule_adherence: {
+        status: "warning" | "compliant" | "violation";
+        rule_id: string;
+        rule_type: string;
+        details?: string | undefined;
+    }[];
+}, {
+    status: "warning" | "compliant" | "violation";
+    policy_id: string;
+    policy_name: string;
+    adherence_percentage: number;
+    rule_adherence: {
+        status: "warning" | "compliant" | "violation";
+        rule_id: string;
+        rule_type: string;
+        details?: string | undefined;
+    }[];
+}>;
+export type PolicyAdherence = z.infer<typeof PolicyAdherenceSchema>;
+/**
+ * Output schema for Usage Oversight Agent
+ *
+ * decision_type: "usage_oversight_signal"
+ */
+export declare const UsageOversightOutputSchema: z.ZodObject<{
+    /** Aggregated usage summary */
+    usage_summary: z.ZodObject<{
+        /** Total requests in period */
+        total_requests: z.ZodNumber;
+        /** Total tokens consumed */
+        total_tokens: z.ZodNumber;
+        /** Total cost in USD */
+        total_cost_usd: z.ZodNumber;
+        /** Average latency in ms */
+        average_latency_ms: z.ZodNumber;
+        /** Unique users */
+        unique_users: z.ZodNumber;
+        /** Unique models used */
+        unique_models: z.ZodNumber;
+        /** Breakdown by model */
+        by_model: z.ZodArray<z.ZodObject<{
+            model: z.ZodString;
+            provider: z.ZodString;
+            requests: z.ZodNumber;
+            tokens: z.ZodNumber;
+            cost_usd: z.ZodNumber;
+            percentage_of_total: z.ZodNumber;
+        }, "strip", z.ZodTypeAny, {
+            model: string;
+            provider: string;
+            cost_usd: number;
+            requests: number;
+            tokens: number;
+            percentage_of_total: number;
+        }, {
+            model: string;
+            provider: string;
+            cost_usd: number;
+            requests: number;
+            tokens: number;
+            percentage_of_total: number;
+        }>, "many">;
+        /** Breakdown by user (top N) */
+        by_user: z.ZodArray<z.ZodObject<{
+            user_id: z.ZodString;
+            requests: z.ZodNumber;
+            tokens: z.ZodNumber;
+            cost_usd: z.ZodNumber;
+            percentage_of_total: z.ZodNumber;
+        }, "strip", z.ZodTypeAny, {
+            user_id: string;
+            cost_usd: number;
+            requests: number;
+            tokens: number;
+            percentage_of_total: number;
+        }, {
+            user_id: string;
+            cost_usd: number;
+            requests: number;
+            tokens: number;
+            percentage_of_total: number;
+        }>, "many">;
+        /** Temporal distribution */
+        temporal_distribution: z.ZodArray<z.ZodObject<{
+            period: z.ZodString;
+            requests: z.ZodNumber;
+            cost_usd: z.ZodNumber;
+        }, "strip", z.ZodTypeAny, {
+            cost_usd: number;
+            period: string;
+            requests: number;
+        }, {
+            cost_usd: number;
+            period: string;
+            requests: number;
+        }>, "many">;
+    }, "strip", z.ZodTypeAny, {
+        total_tokens: number;
+        total_requests: number;
+        total_cost_usd: number;
+        average_latency_ms: number;
+        unique_users: number;
+        unique_models: number;
+        by_model: {
+            model: string;
+            provider: string;
+            cost_usd: number;
+            requests: number;
+            tokens: number;
+            percentage_of_total: number;
+        }[];
+        by_user: {
+            user_id: string;
+            cost_usd: number;
+            requests: number;
+            tokens: number;
+            percentage_of_total: number;
+        }[];
+        temporal_distribution: {
+            cost_usd: number;
+            period: string;
+            requests: number;
+        }[];
+    }, {
+        total_tokens: number;
+        total_requests: number;
+        total_cost_usd: number;
+        average_latency_ms: number;
+        unique_users: number;
+        unique_models: number;
+        by_model: {
+            model: string;
+            provider: string;
+            cost_usd: number;
+            requests: number;
+            tokens: number;
+            percentage_of_total: number;
+        }[];
+        by_user: {
+            user_id: string;
+            cost_usd: number;
+            requests: number;
+            tokens: number;
+            percentage_of_total: number;
+        }[];
+        temporal_distribution: {
+            cost_usd: number;
+            period: string;
+            requests: number;
+        }[];
+    }>;
+    /** Detected out-of-policy patterns */
+    out_of_policy_patterns: z.ZodArray<z.ZodObject<{
+        /** Pattern identifier */
+        pattern_id: z.ZodString;
+        /** Pattern category */
+        category: z.ZodEnum<["cost_anomaly", "usage_spike", "policy_threshold_breach", "quota_warning", "budget_warning", "unusual_model_usage", "off_hours_usage", "high_frequency_usage"]>;
+        /** Severity of the pattern */
+        severity: z.ZodEnum<["info", "advisory", "warning", "alert"]>;
+        /** Human-readable description */
+        description: z.ZodString;
+        /** Affected scope */
+        affected_scope: z.ZodObject<{
+            users: z.ZodArray<z.ZodString, "many">;
+            teams: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
+            models: z.ZodArray<z.ZodString, "many">;
+        }, "strip", z.ZodTypeAny, {
+            models: string[];
+            users: string[];
+            teams?: string[] | undefined;
+        }, {
+            models: string[];
+            users: string[];
+            teams?: string[] | undefined;
+        }>;
+        /** Related policy (if any) */
+        related_policy_id: z.ZodOptional<z.ZodString>;
+        /** Quantitative details */
+        metrics: z.ZodObject<{
+            observed_value: z.ZodNumber;
+            threshold_value: z.ZodOptional<z.ZodNumber>;
+            deviation_percentage: z.ZodOptional<z.ZodNumber>;
+        }, "strip", z.ZodTypeAny, {
+            observed_value: number;
+            threshold_value?: number | undefined;
+            deviation_percentage?: number | undefined;
+        }, {
+            observed_value: number;
+            threshold_value?: number | undefined;
+            deviation_percentage?: number | undefined;
+        }>;
+        /** Timeframe of the pattern */
+        timeframe: z.ZodObject<{
+            start: z.ZodString;
+            end: z.ZodString;
+        }, "strip", z.ZodTypeAny, {
+            start: string;
+            end: string;
+        }, {
+            start: string;
+            end: string;
+        }>;
+    }, "strip", z.ZodTypeAny, {
+        pattern_id: string;
+        category: "cost_anomaly" | "usage_spike" | "policy_threshold_breach" | "quota_warning" | "budget_warning" | "unusual_model_usage" | "off_hours_usage" | "high_frequency_usage";
+        severity: "info" | "advisory" | "warning" | "alert";
+        description: string;
+        affected_scope: {
+            models: string[];
+            users: string[];
+            teams?: string[] | undefined;
+        };
+        metrics: {
+            observed_value: number;
+            threshold_value?: number | undefined;
+            deviation_percentage?: number | undefined;
+        };
+        timeframe: {
+            start: string;
+            end: string;
+        };
+        related_policy_id?: string | undefined;
+    }, {
+        pattern_id: string;
+        category: "cost_anomaly" | "usage_spike" | "policy_threshold_breach" | "quota_warning" | "budget_warning" | "unusual_model_usage" | "off_hours_usage" | "high_frequency_usage";
+        severity: "info" | "advisory" | "warning" | "alert";
+        description: string;
+        affected_scope: {
+            models: string[];
+            users: string[];
+            teams?: string[] | undefined;
+        };
+        metrics: {
+            observed_value: number;
+            threshold_value?: number | undefined;
+            deviation_percentage?: number | undefined;
+        };
+        timeframe: {
+            start: string;
+            end: string;
+        };
+        related_policy_id?: string | undefined;
+    }>, "many">;
+    /** Policy adherence status */
+    policy_adherence: z.ZodArray<z.ZodObject<{
+        /** Policy identifier */
+        policy_id: z.ZodString;
+        /** Policy name */
+        policy_name: z.ZodString;
+        /** Overall adherence status */
+        status: z.ZodEnum<["compliant", "warning", "violation"]>;
+        /** Adherence percentage (0-100) */
+        adherence_percentage: z.ZodNumber;
+        /** Rule-level adherence */
+        rule_adherence: z.ZodArray<z.ZodObject<{
+            rule_id: z.ZodString;
+            rule_type: z.ZodString;
+            status: z.ZodEnum<["compliant", "warning", "violation"]>;
+            details: z.ZodOptional<z.ZodString>;
+        }, "strip", z.ZodTypeAny, {
+            status: "warning" | "compliant" | "violation";
+            rule_id: string;
+            rule_type: string;
+            details?: string | undefined;
+        }, {
+            status: "warning" | "compliant" | "violation";
+            rule_id: string;
+            rule_type: string;
+            details?: string | undefined;
+        }>, "many">;
+    }, "strip", z.ZodTypeAny, {
+        status: "warning" | "compliant" | "violation";
+        policy_id: string;
+        policy_name: string;
+        adherence_percentage: number;
+        rule_adherence: {
+            status: "warning" | "compliant" | "violation";
+            rule_id: string;
+            rule_type: string;
+            details?: string | undefined;
+        }[];
+    }, {
+        status: "warning" | "compliant" | "violation";
+        policy_id: string;
+        policy_name: string;
+        adherence_percentage: number;
+        rule_adherence: {
+            status: "warning" | "compliant" | "violation";
+            rule_id: string;
+            rule_type: string;
+            details?: string | undefined;
+        }[];
+    }>, "many">;
+    /** Budget status */
+    budget_status: z.ZodArray<z.ZodObject<{
+        budget_id: z.ZodString;
+        scope: z.ZodString;
+        scope_id: z.ZodString;
+        limit_usd: z.ZodNumber;
+        current_spend_usd: z.ZodNumber;
+        percentage_used: z.ZodNumber;
+        status: z.ZodEnum<["healthy", "warning", "critical"]>;
+    }, "strip", z.ZodTypeAny, {
+        status: "warning" | "healthy" | "critical";
+        budget_id: string;
+        scope: string;
+        scope_id: string;
+        limit_usd: number;
+        current_spend_usd: number;
+        percentage_used: number;
+    }, {
+        status: "warning" | "healthy" | "critical";
+        budget_id: string;
+        scope: string;
+        scope_id: string;
+        limit_usd: number;
+        current_spend_usd: number;
+        percentage_used: number;
+    }>, "many">;
+    /** Quota status */
+    quota_status: z.ZodArray<z.ZodObject<{
+        quota_id: z.ZodString;
+        quota_type: z.ZodString;
+        scope: z.ZodString;
+        scope_id: z.ZodString;
+        limit_value: z.ZodNumber;
+        current_value: z.ZodNumber;
+        percentage_used: z.ZodNumber;
+        status: z.ZodEnum<["healthy", "warning", "critical"]>;
+    }, "strip", z.ZodTypeAny, {
+        status: "warning" | "healthy" | "critical";
+        scope: string;
+        scope_id: string;
+        quota_id: string;
+        quota_type: string;
+        limit_value: number;
+        current_value: number;
+        percentage_used: number;
+    }, {
+        status: "warning" | "healthy" | "critical";
+        scope: string;
+        scope_id: string;
+        quota_id: string;
+        quota_type: string;
+        limit_value: number;
+        current_value: number;
+        percentage_used: number;
+    }>, "many">;
+    /** Governance health score (0-100) */
+    governance_health_score: z.ZodNumber;
+    /** Recommendations for governance improvement */
+    recommendations: z.ZodArray<z.ZodObject<{
+        recommendation_id: z.ZodString;
+        priority: z.ZodEnum<["low", "medium", "high"]>;
+        category: z.ZodString;
+        description: z.ZodString;
+        action_items: z.ZodArray<z.ZodString, "many">;
+    }, "strip", z.ZodTypeAny, {
+        category: string;
+        description: string;
+        recommendation_id: string;
+        priority: "low" | "medium" | "high";
+        action_items: string[];
+    }, {
+        category: string;
+        description: string;
+        recommendation_id: string;
+        priority: "low" | "medium" | "high";
+        action_items: string[];
+    }>, "many">;
+}, "strip", z.ZodTypeAny, {
+    usage_summary: {
+        total_tokens: number;
+        total_requests: number;
+        total_cost_usd: number;
+        average_latency_ms: number;
+        unique_users: number;
+        unique_models: number;
+        by_model: {
+            model: string;
+            provider: string;
+            cost_usd: number;
+            requests: number;
+            tokens: number;
+            percentage_of_total: number;
+        }[];
+        by_user: {
+            user_id: string;
+            cost_usd: number;
+            requests: number;
+            tokens: number;
+            percentage_of_total: number;
+        }[];
+        temporal_distribution: {
+            cost_usd: number;
+            period: string;
+            requests: number;
+        }[];
+    };
+    out_of_policy_patterns: {
+        pattern_id: string;
+        category: "cost_anomaly" | "usage_spike" | "policy_threshold_breach" | "quota_warning" | "budget_warning" | "unusual_model_usage" | "off_hours_usage" | "high_frequency_usage";
+        severity: "info" | "advisory" | "warning" | "alert";
+        description: string;
+        affected_scope: {
+            models: string[];
+            users: string[];
+            teams?: string[] | undefined;
+        };
+        metrics: {
+            observed_value: number;
+            threshold_value?: number | undefined;
+            deviation_percentage?: number | undefined;
+        };
+        timeframe: {
+            start: string;
+            end: string;
+        };
+        related_policy_id?: string | undefined;
+    }[];
+    policy_adherence: {
+        status: "warning" | "compliant" | "violation";
+        policy_id: string;
+        policy_name: string;
+        adherence_percentage: number;
+        rule_adherence: {
+            status: "warning" | "compliant" | "violation";
+            rule_id: string;
+            rule_type: string;
+            details?: string | undefined;
+        }[];
+    }[];
+    budget_status: {
+        status: "warning" | "healthy" | "critical";
+        budget_id: string;
+        scope: string;
+        scope_id: string;
+        limit_usd: number;
+        current_spend_usd: number;
+        percentage_used: number;
+    }[];
+    quota_status: {
+        status: "warning" | "healthy" | "critical";
+        scope: string;
+        scope_id: string;
+        quota_id: string;
+        quota_type: string;
+        limit_value: number;
+        current_value: number;
+        percentage_used: number;
+    }[];
+    governance_health_score: number;
+    recommendations: {
+        category: string;
+        description: string;
+        recommendation_id: string;
+        priority: "low" | "medium" | "high";
+        action_items: string[];
+    }[];
+}, {
+    usage_summary: {
+        total_tokens: number;
+        total_requests: number;
+        total_cost_usd: number;
+        average_latency_ms: number;
+        unique_users: number;
+        unique_models: number;
+        by_model: {
+            model: string;
+            provider: string;
+            cost_usd: number;
+            requests: number;
+            tokens: number;
+            percentage_of_total: number;
+        }[];
+        by_user: {
+            user_id: string;
+            cost_usd: number;
+            requests: number;
+            tokens: number;
+            percentage_of_total: number;
+        }[];
+        temporal_distribution: {
+            cost_usd: number;
+            period: string;
+            requests: number;
+        }[];
+    };
+    out_of_policy_patterns: {
+        pattern_id: string;
+        category: "cost_anomaly" | "usage_spike" | "policy_threshold_breach" | "quota_warning" | "budget_warning" | "unusual_model_usage" | "off_hours_usage" | "high_frequency_usage";
+        severity: "info" | "advisory" | "warning" | "alert";
+        description: string;
+        affected_scope: {
+            models: string[];
+            users: string[];
+            teams?: string[] | undefined;
+        };
+        metrics: {
+            observed_value: number;
+            threshold_value?: number | undefined;
+            deviation_percentage?: number | undefined;
+        };
+        timeframe: {
+            start: string;
+            end: string;
+        };
+        related_policy_id?: string | undefined;
+    }[];
+    policy_adherence: {
+        status: "warning" | "compliant" | "violation";
+        policy_id: string;
+        policy_name: string;
+        adherence_percentage: number;
+        rule_adherence: {
+            status: "warning" | "compliant" | "violation";
+            rule_id: string;
+            rule_type: string;
+            details?: string | undefined;
+        }[];
+    }[];
+    budget_status: {
+        status: "warning" | "healthy" | "critical";
+        budget_id: string;
+        scope: string;
+        scope_id: string;
+        limit_usd: number;
+        current_spend_usd: number;
+        percentage_used: number;
+    }[];
+    quota_status: {
+        status: "warning" | "healthy" | "critical";
+        scope: string;
+        scope_id: string;
+        quota_id: string;
+        quota_type: string;
+        limit_value: number;
+        current_value: number;
+        percentage_used: number;
+    }[];
+    governance_health_score: number;
+    recommendations: {
+        category: string;
+        description: string;
+        recommendation_id: string;
+        priority: "low" | "medium" | "high";
+        action_items: string[];
+    }[];
+}>;
+export type UsageOversightOutput = z.infer<typeof UsageOversightOutputSchema>;
+export declare function validateUsageOversightInput(input: unknown): UsageOversightInput;
+export declare function validateUsageOversightOutput(output: unknown): UsageOversightOutput;
+/**
+ * CLI invocation shape for Usage Oversight Agent
+ *
+ * Command: llm-gov agent usage-oversight
+ *
+ * Subcommands:
+ * - analyze: Analyze usage patterns for a time range
+ * - inspect: Inspect specific usage records
+ * - summarize: Generate a governance summary
+ *
+ * Examples:
+ *   llm-gov agent usage-oversight analyze --org org_123 --from 2024-01-01 --to 2024-01-31
+ *   llm-gov agent usage-oversight inspect --pattern pattern_456
+ *   llm-gov agent usage-oversight summarize --org org_123 --format json
+ */
+export declare const UsageOversightCLISchema: z.ZodObject<{
+    subcommand: z.ZodEnum<["analyze", "inspect", "summarize"]>;
+    options: z.ZodObject<{
+        organization_id: z.ZodString;
+        from: z.ZodOptional<z.ZodString>;
+        to: z.ZodOptional<z.ZodString>;
+        team_id: z.ZodOptional<z.ZodString>;
+        user_id: z.ZodOptional<z.ZodString>;
+        format: z.ZodDefault<z.ZodEnum<["json", "table", "csv"]>>;
+        verbose: z.ZodDefault<z.ZodBoolean>;
+    }, "strip", z.ZodTypeAny, {
+        organization_id: string;
+        format: "json" | "table" | "csv";
+        verbose: boolean;
+        team_id?: string | undefined;
+        user_id?: string | undefined;
+        from?: string | undefined;
+        to?: string | undefined;
+    }, {
+        organization_id: string;
+        team_id?: string | undefined;
+        user_id?: string | undefined;
+        from?: string | undefined;
+        to?: string | undefined;
+        format?: "json" | "table" | "csv" | undefined;
+        verbose?: boolean | undefined;
+    }>;
+}, "strip", z.ZodTypeAny, {
+    options: {
+        organization_id: string;
+        format: "json" | "table" | "csv";
+        verbose: boolean;
+        team_id?: string | undefined;
+        user_id?: string | undefined;
+        from?: string | undefined;
+        to?: string | undefined;
+    };
+    subcommand: "analyze" | "inspect" | "summarize";
+}, {
+    options: {
+        organization_id: string;
+        team_id?: string | undefined;
+        user_id?: string | undefined;
+        from?: string | undefined;
+        to?: string | undefined;
+        format?: "json" | "table" | "csv" | undefined;
+        verbose?: boolean | undefined;
+    };
+    subcommand: "analyze" | "inspect" | "summarize";
+}>;
+export type UsageOversightCLI = z.infer<typeof UsageOversightCLISchema>;
+export declare const USAGE_OVERSIGHT_AGENT_METADATA: {
+    readonly agent_id: "usage-oversight-agent";
+    readonly agent_version: "1.0.0";
+    readonly classification: "OVERSIGHT";
+    readonly decision_type: "usage_oversight_signal";
+    readonly description: "Provide visibility into LLM usage patterns for governance and compliance monitoring";
+    readonly capabilities: readonly ["Aggregate usage signals across systems", "Identify out-of-policy usage patterns", "Produce oversight dashboards and signals", "Calculate governance health scores", "Generate adherence reports"];
+    readonly restrictions: readonly ["MUST NOT intercept execution", "MUST NOT trigger retries or workflows", "MUST NOT enforce policies", "MUST NOT modify configurations", "MUST NOT emit anomaly detections", "MUST NOT apply optimizations", "MUST NOT connect directly to Google SQL", "MUST NOT execute SQL queries"];
+    readonly consumers: readonly ["Governance & compliance dashboards", "Audit systems", "Management reporting", "Policy recommendation systems"];
+    readonly persistence: {
+        readonly persisted_to: "ruvector-service";
+        readonly data_persisted: readonly ["DecisionEvent", "UsageOversightOutput"];
+        readonly data_not_persisted: readonly ["Raw usage patterns (already in source systems)", "PII beyond user IDs", "Actual prompt/completion content"];
+    };
+};
+//# sourceMappingURL=usage-oversight.d.ts.map