@muxoai/sdk 1.3.0 → 1.4.3

package/dist/policy.d.ts

@@ -0,0 +1,190 @@
+import type { GovernancePolicy, HumanFriendlyExplanation, LanguageMode, ParameterPolicyRule, RiskLevel } from "./types.js";
+export declare function sanitizeParameterPolicyRule(r: Record<string, unknown>, idx?: number): ParameterPolicyRule;
+export declare class PolicyValidationError extends Error {
+}
+export declare function formatHumanFriendlyExplanation(params: {
+    headline: string;
+    nonTechnical: string;
+    technical: string;
+    policy?: Partial<GovernancePolicy> | null;
+    languageMode?: LanguageMode;
+}): HumanFriendlyExplanation;
+/**
+ * Validates a client-supplied policy patch. Kill-switch fields are rejected so
+ * that pausing and resuming always goes through /api/v1/governance/kill-switch,
+ * which records the trust-score penalty and audit entry.
+ */
+export declare function sanitizePolicyPatch(body: unknown): Partial<GovernancePolicy>;
+export declare const DEFAULT_WORKSPACE_POLICY: GovernancePolicy;
+export interface ParsedNaturalLanguageGuardrail {
+    isGuardrail: boolean;
+    patch: Partial<GovernancePolicy>;
+    ruleText: string;
+    summary: string;
+    humanRules: string[];
+    compiledBy?: "deterministic" | "llm" | "mcp_harness";
+    memoryFact: {
+        title: string;
+        content: string;
+        subject: string;
+        predicate: string;
+        object: string;
+        tags: string[];
+    };
+}
+export interface GuardrailCompileOptions {
+    parameterRules?: Array<Record<string, unknown> | ParameterPolicyRule>;
+    policyPatch?: Partial<GovernancePolicy>;
+    source?: ParameterPolicyRule["source"];
+    llmApiKey?: string | null;
+    llmProvider?: "openai" | "anthropic";
+}
+/**
+ * Compiles plain-English user guardrails (e.g. "Hey Muxo, don't go over 25 credits",
+ * "Only allow sending emails to @muxo.ai", or "Require approval for Stripe refunds over $50,
+ * auto-approve under $50") and/or structured MCP harness parameter rules into enforced
+ * GovernancePolicy fields while keeping human-readable rule descriptions.
+ */
+export declare function parseNaturalLanguageGuardrail(prompt: string, currentPolicy?: GovernancePolicy, options?: GuardrailCompileOptions): ParsedNaturalLanguageGuardrail;
+/**
+ * Async LLM-assisted policy compiler: first runs deterministic semantic compilation
+ * (plus any structured `parameterRules` supplied by an MCP LLM harness), and when an
+ * OpenAI or Anthropic key is available and a complex natural-language rule produced no
+ * structured patch fields, invokes the LLM to synthesize validated `ParameterPolicyRule[]`.
+ */
+export declare function compileNaturalLanguageGuardrailWithLlm(prompt: string, currentPolicy?: GovernancePolicy, options?: GuardrailCompileOptions): Promise<ParsedNaturalLanguageGuardrail>;
+export declare function describePolicyInPlainEnglish(policy?: GovernancePolicy): {
+    headline: string;
+    rules: string[];
+    activeCustomRules: string[];
+    badges: Array<{
+        label: string;
+        tone: "safe" | "warn" | "strict";
+    }>;
+    languageMode: LanguageMode;
+    customInstructions: string[];
+    nonTechnical: string;
+    technical: string;
+    preferred: string;
+    explanation: HumanFriendlyExplanation;
+};
+export declare function evaluateParameterPolicyRules(paramsOrToolSlug: {
+    policy?: Partial<GovernancePolicy> | null;
+    toolSlug: string;
+    input: Record<string, unknown>;
+} | string, maybeInput?: Record<string, unknown>, maybePolicy?: Partial<GovernancePolicy> | null): {
+    violated: boolean;
+    allowed: boolean;
+    explicitAllow: boolean;
+    action: "allow" | "auto_approve" | "block" | "deny" | "require_approval";
+    matchedRule: ParameterPolicyRule | null;
+    violatedRule: ParameterPolicyRule | null;
+    reason: string | null;
+};
+export declare function describeParameterRuleCompliance(rule: ParameterPolicyRule): string;
+export interface LlmRiskLaneRule {
+    riskLevel: RiskLevel;
+    status: "auto_approved" | "requires_approval" | "blocked";
+    executeTool: string;
+    reason: string;
+}
+export interface LlmPolicyAndGovernanceBrief {
+    workspaceId?: string;
+    posture: "paused" | "read_only_sandbox" | "ask_every_time" | "safe_default" | "hands_off" | "monitor";
+    mode: "enforce" | "monitor";
+    executionRing: 0 | 1 | 2 | 3;
+    headline: string;
+    preferredExplanation: string;
+    plainEnglish: ReturnType<typeof describePolicyInPlainEnglish>;
+    languageMode: LanguageMode;
+    customInstructions: string[];
+    killSwitch: {
+        active: boolean;
+        reason: string | null;
+        howToToggleMcp: {
+            pause: {
+                tool: "get_run_context";
+                arguments: Record<string, unknown>;
+            };
+            resume: {
+                tool: "get_run_context";
+                arguments: Record<string, unknown>;
+            };
+        };
+    };
+    budgetGuardrail: {
+        maxCreditsPerRun: number;
+        maxUsdPerRun: number;
+        allowInstantWallet: boolean;
+        allowProvisioning: boolean;
+        blockDestructiveSql: boolean;
+    };
+    riskLaneMatrix: Record<RiskLevel, LlmRiskLaneRule>;
+    autoApproveRiskLevels: RiskLevel[];
+    requireApprovalRiskLevels: RiskLevel[];
+    blockedRiskLevels: RiskLevel[];
+    blockedToolSlugs: string[];
+    parameterRules: Array<ParameterPolicyRule & {
+        howToComply: string;
+    }>;
+    naturalLanguageRules: string[];
+    activeDefaults: Record<string, unknown>;
+    trustScore?: {
+        overall: number;
+        tier: string;
+    };
+    agentDid?: string;
+    llmSystemDirective: string;
+    agentControlCheatsheet: Array<{
+        intent: string;
+        mcpTool: string;
+        arguments: Record<string, unknown>;
+    }>;
+}
+export declare function buildLlmPolicyAndGovernanceBrief(policy?: GovernancePolicy, options?: {
+    workspaceId?: string;
+    workspaceName?: string;
+    workspaceSlug?: string;
+    activeDefaults?: Record<string, unknown>;
+    trustScore?: {
+        overall: number;
+        tier: string;
+    };
+    agentDid?: string;
+}): LlmPolicyAndGovernanceBrief;
+export interface PolicySimulationResult {
+    ok: true;
+    action: "check_policy";
+    toolSlug: string;
+    toolName?: string;
+    riskLevel: RiskLevel;
+    creditCost: number;
+    decision: "auto_approved" | "pending_approval" | "blocked";
+    approvalStatus: "auto_approved" | "pending_approval" | "blocked";
+    allowed: boolean;
+    requiresApproval: boolean;
+    blocked: boolean;
+    executeTool: string;
+    effectiveInput: Record<string, unknown>;
+    autoFilledInput: Record<string, unknown>;
+    reasons: string[];
+    matchedParameterRule: ParameterPolicyRule | null;
+    violatedParameterRule: ParameterPolicyRule | null;
+    remediationForLlm: string;
+    nextToolCalls: Array<{
+        tool: string;
+        input: Record<string, unknown>;
+        when: string;
+    }>;
+}
+export declare function simulatePolicyEvaluation(params: {
+    policy?: GovernancePolicy | null;
+    toolSlug: string;
+    toolName?: string;
+    riskLevel?: RiskLevel;
+    creditCost?: number;
+    creditsBalance?: number;
+    lane?: string;
+    input?: Record<string, unknown>;
+    activeDefaults?: Record<string, unknown>;
+}): PolicySimulationResult;