@muxoai/platform 1.4.0 → 1.4.1

package/dist/providers/microsoft-governance.d.ts

@@ -1,5 +1,5 @@
 import { AgentIdentity, AuditLogger, type ContextPoisoningScanResult, type KillSwitchResult, type TrustScore } from "../../vendor/microsoft-governance/dist/index.js";
-import type { ActionPlan, GovernanceDecisionRecord, MuxoTool, Workspace } from "../types.js";
+import type { ActionPlan, ExecutionReceipt, ExecutionRun, GovernanceDecisionRecord, GovernancePolicy, HumanFriendlyExplanation, LanguageMode, MuxoTool, PortableAgenticReceipt, Workspace } from "../types.js";
 export declare const RING_LABELS: Record<number, string>;
 export declare class MicrosoftGovernanceAdapter {
     private readonly scanner;
@@ -108,6 +108,20 @@ export declare class MicrosoftGovernanceAdapter {
      * Verifies a DecisionRecord's Ed25519 signature and the workspace's SHA-256 audit hash chain.
      */
     verifyDecisionRecord(workspaceOrRecord: Workspace | GovernanceDecisionRecord, maybeRecord?: GovernanceDecisionRecord): boolean;
+    /**
+     * Builds a portable Ed25519-signed AgenticReceipt envelope (compatible with the `agentic-receipts` spec)
+     * so external verifiers can validate input/output SHA-256 hashes, hash chaining, and Ed25519 signature
+     * using only the workspace's public key and DID without needing the internal vault HMAC key.
+     */
+    buildPortableAgenticReceipt(params: {
+        receipt: ExecutionReceipt;
+        run?: ExecutionRun | null;
+        workspace?: Workspace | null;
+    }): PortableAgenticReceipt;
+    /**
+     * Verifies a PortableAgenticReceipt's Ed25519 signature over its canonical hash-chained payload.
+     */
+    verifyPortableAgenticReceipt(agenticReceipt: PortableAgenticReceipt, workspace?: Workspace | null): boolean;
     getStatus(workspace?: Workspace): {
         sdk: string;
         sdkVersion: string;
@@ -123,3 +137,16 @@ export declare class MicrosoftGovernanceAdapter {
      */
     getGovernanceStatus(workspace: Workspace): Record<string, unknown>;
 }
+export declare function explainDecisionRecord(record: GovernanceDecisionRecord, policy?: Partial<GovernancePolicy> | null, languageMode?: LanguageMode): HumanFriendlyExplanation;
+export declare function explainGovernanceStatus(params: {
+    workspace: Workspace;
+    agentDid: string;
+    trustScore: NonNullable<GovernanceDecisionRecord["trustScore"]>;
+    killSwitchActive: boolean;
+    killSwitchReason: string | null;
+    poisoned: boolean;
+    findingsCount: number;
+    auditEntriesCount: number;
+    chainVerified: boolean;
+    languageMode?: LanguageMode;
+}): HumanFriendlyExplanation;

package/dist/providers/microsoft-governance.js

@@ -1,5 +1,6 @@
 import crypto from "node:crypto";
 import { AgentIdentity, AuditLogger, ContextPoisoningDetector, ExecutionRing, FacetRegistry, KillSwitch, McpSecurityScanner, PolicyEngine, RingEnforcer, TrustManager, extractK8sFacets, extractProtocolFacets, extractSqlFacets, } from "../../vendor/microsoft-governance/dist/index.js";
+import { describePolicyInPlainEnglish, evaluateParameterPolicyRules, formatHumanFriendlyExplanation, } from "../policy.js";
 const SDK_VERSION = "5.0.0";
 const POLICY_ID = "muxo-microsoft-agent-governance-v5";
 export const RING_LABELS = {
@@ -555,10 +556,24 @@ export class MicrosoftGovernanceAdapter {
         const highSeverityFinding = extraFindings.some((f) => f.severity === "high" || f.severity === "critical");
         // 2. Protocol Facets Extraction (SQL, Kubernetes, Infrastructure)
         const protocolFacets = this.extractActionFacets(tool, input);
-        // 3. Hardware-style Execution Ring Enforcement (Ring 0..Ring 3)
-        const ringEnforcement = this.evaluateRingEnforcement(workspace, tool, ownerApproved);
-        // 4. PolicyEngine + KillSwitch evaluation
+        // 3. PolicyEngine + KillSwitch + Parameter Guardrail evaluation
         const policy = workspace.policy;
+        const paramRuleCheck = evaluateParameterPolicyRules({
+            policy,
+            toolSlug: tool.slug,
+            input,
+        });
+        if (paramRuleCheck.violated && paramRuleCheck.reason) {
+            extraFindings.push({
+                category: "parameter_policy_rule",
+                severity: paramRuleCheck.action === "block" ? "high" : "medium",
+                description: paramRuleCheck.reason,
+            });
+        }
+        const effectiveApproved = ownerApproved ||
+            Boolean(paramRuleCheck.explicitAllow && paramRuleCheck.action === "auto_approve");
+        // 4. Hardware-style Execution Ring Enforcement (Ring 0..Ring 3)
+        const ringEnforcement = this.evaluateRingEnforcement(workspace, tool, effectiveApproved);
         const activeKill = this.isKillSwitchActive(workspace.id);
         const killSwitchActive = Boolean(activeKill || policy.killSwitchActive);
         const killSwitchReason = activeKill?.reason || policy.killSwitchReason || null;
@@ -569,7 +584,7 @@ export class MicrosoftGovernanceAdapter {
             risk_level: tool.riskLevel,
             lane: tool.lane,
             stage,
-            owner_approved: ownerApproved,
+            owner_approved: effectiveApproved,
             workspace_active: true,
             ...(protocolFacets.sql ? { sql: protocolFacets.sql } : {}),
             ...(protocolFacets.k8s ? { k8s: protocolFacets.k8s } : {}),
@@ -580,8 +595,12 @@ export class MicrosoftGovernanceAdapter {
             : policyDecision.action === "require_approval"
                 ? "require_approval"
                 : "allow";
-        let matchedRule = policyDecision.matchedRule ?? null;
-        // Enforce KillSwitch, blocked tools, high-severity scanner/context-poisoning findings, or Ring breach
+        let matchedRule = paramRuleCheck.explicitAllow &&
+            paramRuleCheck.action === "auto_approve" &&
+            finalDecision === "allow"
+            ? paramRuleCheck.matchedRule?.id || "auto-approve-parameter-policy-rule"
+            : policyDecision.matchedRule ?? null;
+        // Enforce KillSwitch, blocked tools, parameter rules, high-severity scanner/context-poisoning findings, or Ring breach
         if (killSwitchActive) {
             finalDecision = "deny";
             matchedRule = "kill-switch-emergency-quarantine";
@@ -590,6 +609,19 @@ export class MicrosoftGovernanceAdapter {
             finalDecision = "deny";
             matchedRule = matchedRule || `deny-blocked-tool-${tool.slug}`;
         }
+        else if (paramRuleCheck.violated &&
+            paramRuleCheck.action === "block" &&
+            policy.mode === "enforce") {
+            finalDecision = "deny";
+            matchedRule = paramRuleCheck.matchedRule?.id || "deny-parameter-policy-rule";
+        }
+        else if (paramRuleCheck.violated &&
+            paramRuleCheck.action === "require_approval" &&
+            !ownerApproved &&
+            policy.mode === "enforce") {
+            finalDecision = "require_approval";
+            matchedRule = paramRuleCheck.matchedRule?.id || "approval-parameter-policy-rule";
+        }
         else if (highSeverityFinding && policy.mode === "enforce") {
             finalDecision = "deny";
             matchedRule = "mcp-security-scanner-high-severity";
@@ -651,13 +683,17 @@ export class MicrosoftGovernanceAdapter {
         const decisionReason = finalDecision === "deny"
             ? killSwitchActive
                 ? `Blocked by Emergency KillSwitch: ${killSwitchReason || "Workspace agent boundary is quarantined"}`
-                : highSeverityFinding
-                    ? `Blocked by McpSecurityScanner / ContextPoisoningDetector: ${extraFindings.map((f) => f.description).join("; ")}`
-                    : `Denied by policy rule ${matchedRule || "default"}`
+                : paramRuleCheck.violated && paramRuleCheck.reason
+                    ? paramRuleCheck.reason
+                    : highSeverityFinding
+                        ? `Blocked by McpSecurityScanner / ContextPoisoningDetector: ${extraFindings.map((f) => f.description).join("; ")}`
+                        : `Denied by policy rule ${matchedRule || "default"}`
             : finalDecision === "require_approval"
-                ? `Escalated for human owner approval (${tool.riskLevel} risk lane, ${ringEnforcement.ringLabel})`
+                ? paramRuleCheck.violated && paramRuleCheck.reason
+                    ? paramRuleCheck.reason
+                    : `Escalated for human owner approval (${tool.riskLevel} risk lane, ${ringEnforcement.ringLabel})`
                 : `Allowed by Microsoft Agent Governance (${matchedRule || "allow-governed-action"})`;
-        return {
+        const record = {
             id: `dec_${crypto.randomBytes(8).toString("hex")}`,
             sdk: "@microsoft/agent-governance-sdk",
             sdkVersion: SDK_VERSION,
@@ -711,6 +747,8 @@ export class MicrosoftGovernanceAdapter {
             bindingHash,
             decidedAt,
         };
+        record.explanation = explainDecisionRecord(record, policy);
+        return record;
     }
     evaluatePlan(params) {
         return this.evaluateAction({
@@ -775,6 +813,112 @@ export class MicrosoftGovernanceAdapter {
         const auditChainVerified = auditLogger.verify();
         return ed25519Verified && auditChainVerified;
     }
+    /**
+     * Builds a portable Ed25519-signed AgenticReceipt envelope (compatible with the `agentic-receipts` spec)
+     * so external verifiers can validate input/output SHA-256 hashes, hash chaining, and Ed25519 signature
+     * using only the workspace's public key and DID without needing the internal vault HMAC key.
+     */
+    buildPortableAgenticReceipt(params) {
+        const { receipt, run, workspace } = params;
+        const identity = workspace
+            ? this.getWorkspaceIdentity(workspace)
+            : this.identities.get(receipt.workspaceId) || this.defaultIdentity;
+        const actionType = receipt.lane === "stripe_projects" ? "ApiCall" : "ToolCall";
+        const startedAt = run?.startedAt || receipt.issuedAt;
+        const completedAt = run?.completedAt || receipt.issuedAt;
+        const latencyMs = Math.max(0, Number(run?.durationMs ?? 0));
+        const nonce = crypto
+            .createHash("sha256")
+            .update(`muxo-agentic-receipt-nonce:${receipt.id}:${receipt.runId}`)
+            .digest("hex")
+            .slice(0, 32);
+        const previousReceiptHash = receipt.prevReceiptHash || "genesis_0000000000000000";
+        const canonicalPayload = [
+            "0.1.0",
+            receipt.id,
+            identity.did,
+            receipt.runId,
+            actionType,
+            receipt.toolSlug || "",
+            receipt.inputHash,
+            receipt.outputHash,
+            startedAt,
+            completedAt,
+            String(latencyMs),
+            nonce,
+            previousReceiptHash || "genesis",
+            receipt.receiptHash,
+        ].join("|");
+        const sigBytes = identity.sign(Buffer.from(canonicalPayload, "utf8"));
+        const signatureHex = Buffer.from(sigBytes).toString("hex");
+        const publicKeyHex = Buffer.from(identity.publicKey).toString("hex");
+        return {
+            version: "0.1.0",
+            receipt_id: receipt.id,
+            agent_id: identity.did,
+            task_id: receipt.runId,
+            action_type: actionType,
+            tool_name: receipt.toolSlug,
+            model_id: null,
+            input_hash: receipt.inputHash,
+            output_hash: receipt.outputHash,
+            started_at: startedAt,
+            completed_at: completedAt,
+            latency_ms: latencyMs,
+            nonce,
+            previous_receipt_hash: previousReceiptHash,
+            receipt_hash: receipt.receiptHash,
+            signature_algorithm: "Ed25519",
+            public_key_hex: publicKeyHex,
+            signature_hex: signatureHex,
+        };
+    }
+    /**
+     * Verifies a PortableAgenticReceipt's Ed25519 signature over its canonical hash-chained payload.
+     */
+    verifyPortableAgenticReceipt(agenticReceipt, workspace) {
+        if (!agenticReceipt || !agenticReceipt.signature_hex || !agenticReceipt.public_key_hex) {
+            return false;
+        }
+        const canonicalPayload = [
+            agenticReceipt.version || "0.1.0",
+            agenticReceipt.receipt_id,
+            agenticReceipt.agent_id,
+            agenticReceipt.task_id,
+            agenticReceipt.action_type,
+            agenticReceipt.tool_name || "",
+            agenticReceipt.input_hash,
+            agenticReceipt.output_hash,
+            agenticReceipt.started_at,
+            agenticReceipt.completed_at,
+            String(agenticReceipt.latency_ms ?? 0),
+            agenticReceipt.nonce,
+            agenticReceipt.previous_receipt_hash || "genesis",
+            agenticReceipt.receipt_hash,
+        ].join("|");
+        try {
+            const identity = workspace ? this.getWorkspaceIdentity(workspace) : null;
+            if (identity && identity.did === agenticReceipt.agent_id) {
+                return identity.verify(Buffer.from(canonicalPayload, "utf8"), Buffer.from(agenticReceipt.signature_hex, "hex"));
+            }
+            const pubKeyBytes = Buffer.from(agenticReceipt.public_key_hex, "hex");
+            const spkiKey = pubKeyBytes.length === 32
+                ? Buffer.concat([
+                    Buffer.from("302a300506032b6570032100", "hex"),
+                    pubKeyBytes,
+                ])
+                : pubKeyBytes;
+            const pubKeyObj = crypto.createPublicKey({
+                key: spkiKey,
+                format: "der",
+                type: "spki",
+            });
+            return crypto.verify(null, Buffer.from(canonicalPayload, "utf8"), pubKeyObj, Buffer.from(agenticReceipt.signature_hex, "hex"));
+        }
+        catch {
+            return false;
+        }
+    }
     getStatus(workspace) {
         const identity = workspace
             ? this.getWorkspaceIdentity(workspace)
@@ -844,6 +988,75 @@ export class MicrosoftGovernanceAdapter {
                 chainVerified: auditLogger.verify(),
                 recentEntries: entries.slice(-15).reverse(),
             },
+            plainEnglishPolicy: describePolicyInPlainEnglish(workspace.policy),
+            explanation: explainGovernanceStatus({
+                workspace,
+                agentDid: identity.did,
+                trustScore: this.getWorkspaceTrustScore(workspace.id),
+                killSwitchActive,
+                killSwitchReason: activeKill?.reason || workspace.policy.killSwitchReason || null,
+                poisoned: Boolean(contextPoisoningReport.poisoned ??
+                    (contextPoisoningReport.findings?.length > 0)),
+                findingsCount: contextPoisoningReport.findings.length,
+                auditEntriesCount: entries.length,
+                chainVerified: auditLogger.verify(),
+            }),
         };
     }
 }
+export function explainDecisionRecord(record, policy, languageMode) {
+    const toolSlug = record.action.includes(":")
+        ? record.action.split(":").slice(1).join(":")
+        : record.action;
+    const stage = record.action.startsWith("execute.") ? "Execution" : "Plan";
+    const headline = record.decision === "allow"
+        ? `${stage} allowed: ${toolSlug} passed all workspace safety checks.`
+        : record.decision === "require_approval"
+            ? `Approval needed: ${toolSlug} (${record.riskLevel}) is paused until you approve it.`
+            : `Action blocked: ${toolSlug} was stopped by your workspace safety rules.`;
+    const scanPlain = record.securityScan.safe
+        ? "Safety scan: Clean (no prompt injection, data exfiltration, or destructive command patterns detected)."
+        : `Safety warning: Flagged ${record.securityScan.findingsCount} security issue(s) (${record.securityScan.findings.map((f) => f.description).join("; ")}).`;
+    const whyPlain = record.decision === "allow"
+        ? `This ${record.riskLevel}-level action is permitted under your active guardrails.`
+        : record.decision === "require_approval"
+            ? `Your guardrails require human sign-off before running ${record.riskLevel} actions.`
+            : record.killSwitch?.active
+                ? `Your workspace Emergency Pause is active (${record.killSwitch.reason || "all agents paused"}).`
+                : `Stopped because: ${record.reason}.`;
+    const trustPct = record.trustScore
+        ? `${Math.round(record.trustScore.overall * 100)}% (${record.trustScore.tier})`
+        : "75% (Provisional)";
+    const nonTechnical = `${headline} ${whyPlain} ${scanPlain} Agent reliability score: ${trustPct}. Recorded in your tamper-proof audit log.`;
+    const technical = `decisionId=${record.id} | decision=${record.decision} (verdict=${record.verdict}) | matchedRule=${record.matchedRule || "none"} | mode=${record.mode} | ring=${record.ringEnforcement?.agentRing ?? "?"}->${record.ringEnforcement?.requiredRing ?? "?"} (${record.ringEnforcement?.ringLabel || "Ring"}) | securityScan=(safe=${record.securityScan.safe}, risk=${record.securityScan.riskLevel}, findings=${record.securityScan.findingsCount}) | asi06Poisoning=(safe=${record.contextPoisoning?.safe ?? true}, risk=${record.contextPoisoning?.riskLevel || "none"}) | trustScore=${record.trustScore?.overall ?? 0.75} (${record.trustScore?.tier || "Provisional"}) | agentDid=${record.agentDid} | auditHash=${record.auditEntry.hash.slice(0, 16)}... (prev=${record.auditEntry.previousHash.slice(0, 16)}..., chainVerified=${record.auditEntry.chainVerified}) | bindingHash=${record.bindingHash.slice(0, 16)}... | ed25519Sig=${record.ed25519Signature.slice(0, 16)}...`;
+    return formatHumanFriendlyExplanation({
+        headline,
+        nonTechnical,
+        technical,
+        policy,
+        languageMode,
+    });
+}
+export function explainGovernanceStatus(params) {
+    const plainPolicy = describePolicyInPlainEnglish(params.workspace.policy);
+    const trustPct = Math.round((params.trustScore.overall || 0.75) * 100);
+    const headline = params.killSwitchActive
+        ? `Emergency Pause Active: All agent actions are paused (${params.killSwitchReason || "operator pause"}).`
+        : `Governance Active: 9 safety modules protecting ${params.workspace.name} (${params.trustScore.tier} trust, ${trustPct}% score).`;
+    const nonTechnical = [
+        headline,
+        `Current posture: ${plainPolicy.headline}`,
+        params.poisoned
+            ? `Prompt-injection scanner: ${params.findingsCount} suspicious pattern(s) flagged and isolated.`
+            : "Prompt-injection & memory scanner: Clean (0 threats detected).",
+        `Tamper-proof audit log: ${params.auditEntriesCount} action${params.auditEntriesCount === 1 ? "" : "s"} verified (${params.chainVerified ? "intact" : "check required"}).`,
+    ].join(" ");
+    const technical = `sdk=@microsoft/agent-governance-sdk@${SDK_VERSION} | policyId=${POLICY_ID} | agentDid=${params.agentDid} | killSwitchActive=${params.killSwitchActive} | trustScore=${params.trustScore.overall} (tier=${params.trustScore.tier}, reliability=${params.trustScore.reliability}, consistency=${params.trustScore.consistency}) | asi06Poisoned=${params.poisoned} (findings=${params.findingsCount}) | auditChain=(entries=${params.auditEntriesCount}, verified=${params.chainVerified}) | ${plainPolicy.technical}`;
+    return formatHumanFriendlyExplanation({
+        headline,
+        nonTechnical,
+        technical,
+        policy: params.workspace.policy,
+        languageMode: params.languageMode,
+    });
+}

package/dist/providers/stripe-billing.d.ts

@@ -1,11 +1,27 @@
 import type { MuxoConfig } from "../config.js";
 import type { MuxoStore } from "../store.js";
 import type { ToolDescriptor, Workspace } from "../types.js";
+export declare const BILLING_TOOLS: ToolDescriptor[];
+export interface StripeMeterEventRecord {
+    identifier: string;
+    event_name: string;
+    timestamp: string;
+    workspaceId: string;
+    stripe_customer_id: string;
+    value: number;
+    lane: string;
+    tool_slug: string;
+    livemode: boolean;
+    source: "stripe_v2_meter_stream" | "muxo_local_meter";
+}
 export declare class StripeBillingAdapter {
     private readonly config;
     private readonly store;
     private resolvedStarterPriceId;
     private resolvedCreditsPriceId;
+    private meterSessionToken;
+    private readonly meterEvents;
+    private readonly seenMeterIdentifiers;
     constructor(config: MuxoConfig, store: MuxoStore);
     private getEffectiveStripeKey;
     get isConfigured(): boolean;
@@ -38,4 +54,30 @@ export declare class StripeBillingAdapter {
         input: Record<string, unknown>;
     }): Promise<Record<string, unknown>>;
     verifyWebhookSignature(rawBody: string, signatureHeader: string): boolean;
+    createMeterEventSession(workspaceId?: string): Promise<{
+        object: "v2.billing.meter_event_session";
+        authentication_token: string;
+        created: string;
+        expires_at: string;
+        livemode: boolean;
+        source: "stripe_v2_api" | "muxo_managed";
+    }>;
+    recordMeterEvent(params: {
+        workspace: Workspace;
+        event_name?: string;
+        value: number;
+        lane?: string;
+        tool_slug?: string;
+        identifier?: string;
+        timestamp?: string;
+    }): Promise<{
+        recorded: boolean;
+        deduplicated: boolean;
+        event: StripeMeterEventRecord;
+    }>;
+    listMeterEvents(workspaceId: string, limit?: number): {
+        events: StripeMeterEventRecord[];
+        totalValue: number;
+        byLane: Record<string, number>;
+    };
 }

package/dist/providers/stripe-billing.js

@@ -1,5 +1,5 @@
 import crypto from "node:crypto";
-const BILLING_TOOLS = [
+export const BILLING_TOOLS = [
     {
         slug: "billing.credits.topup",
         upstreamSlug: "STRIPE_BILLING_CREDITS_TOPUP",
@@ -79,12 +79,49 @@ const BILLING_TOOLS = [
             required: ["kind"],
         },
     },
+    {
+        slug: "billing.stripe.create_refund",
+        upstreamSlug: "STRIPE_CREATE_REFUND",
+        name: "Stripe: Create Refund",
+        description: "Issue a partial or full Stripe refund for a charge or payment intent. Supports conditional dollar threshold guardrails (e.g. auto-approve under $50, require approval over $50).",
+        lane: "stripe_projects",
+        providerSlug: "stripe_billing",
+        providerName: "Stripe Billing",
+        categories: ["billing", "finance"],
+        riskLevel: "financial",
+        requiresAuth: false,
+        creditCost: 0,
+        billingMode: "provider_wallet",
+        inputSchema: {
+            type: "object",
+            properties: {
+                charge_id: {
+                    type: "string",
+                    description: "Stripe Charge ID (ch_...) or PaymentIntent ID (pi_...)",
+                },
+                amount: {
+                    type: "number",
+                    description: "Refund amount in USD dollars (e.g. 25 for $25.00)",
+                },
+                reason: {
+                    type: "string",
+                    enum: ["duplicate", "fraudulent", "requested_by_customer"],
+                    default: "requested_by_customer",
+                    description: "Reason for refund",
+                },
+            },
+            required: ["amount"],
+        },
+    },
 ];
 export class StripeBillingAdapter {
     config;
     store;
     resolvedStarterPriceId = null;
     resolvedCreditsPriceId = null;
+    meterSessionToken = null;
+    meterEvents = [];
+    seenMeterIdentifiers = new Set();
     constructor(config, store) {
         this.config = config;
         this.store = store;
@@ -360,6 +397,28 @@ export class StripeBillingAdapter {
                 ...checkout,
             };
         }
+        if (params.toolSlug === "billing.stripe.create_refund") {
+            const amountUsd = Number(params.input.amount ??
+                params.input.amount_usd ??
+                (params.input.amount_cents ? Number(params.input.amount_cents) / 100 : 0));
+            const chargeId = String(params.input.charge_id ||
+                params.input.payment_intent ||
+                `ch_muxo_${crypto.randomBytes(6).toString("hex")}`);
+            const reason = String(params.input.reason || "requested_by_customer");
+            return {
+                provider: "stripe_billing",
+                action: "create_refund",
+                id: `re_muxo_${crypto.randomBytes(8).toString("hex")}`,
+                object: "refund",
+                charge: chargeId,
+                amount: Math.round(amountUsd * 100),
+                amount_usd: amountUsd,
+                currency: "usd",
+                reason,
+                status: "succeeded",
+                created: Math.floor(Date.now() / 1000),
+            };
+        }
         throw new Error(`Unsupported billing tool: ${params.toolSlug}`);
     }
     verifyWebhookSignature(rawBody, signatureHeader) {
@@ -379,4 +438,174 @@ export class StripeBillingAdapter {
             .digest("hex");
         return crypto.timingSafeEqual(Buffer.from(expectedSig, "hex"), Buffer.from(computed, "hex"));
     }
+    // Stripe v2 Billing Meter Event Stream (`POST /v2/billing/meter_event_session` + `POST /v2/billing/meter_event_stream`)
+    async createMeterEventSession(workspaceId) {
+        const key = this.getEffectiveStripeKey(workspaceId);
+        const base = this.config.stripeApiBaseUrl.replace(/\/v1\/?$/, "");
+        if (key) {
+            try {
+                const res = await fetch(`${base}/v2/billing/meter_event_session`, {
+                    method: "POST",
+                    headers: {
+                        Authorization: `Bearer ${key}`,
+                        "Stripe-Version": this.config.stripeProvisioningApiVersion || "2026-09-30.preview",
+                        Accept: "application/json",
+                    },
+                    signal: AbortSignal.timeout(10_000),
+                });
+                if (res.ok) {
+                    const data = (await res.json());
+                    const token = String(data.authentication_token || "");
+                    const expMs = data.expires_at
+                        ? new Date(String(data.expires_at)).getTime()
+                        : Date.now() + 14 * 60_000;
+                    if (token) {
+                        this.meterSessionToken = { token, expiresAt: expMs };
+                    }
+                    return {
+                        object: "v2.billing.meter_event_session",
+                        authentication_token: token,
+                        created: String(data.created || new Date().toISOString()),
+                        expires_at: String(data.expires_at || new Date(expMs).toISOString()),
+                        livemode: Boolean(data.livemode),
+                        source: "stripe_v2_api",
+                    };
+                }
+            }
+            catch {
+                // Fall through to managed meter session token
+            }
+        }
+        const expiresAt = Date.now() + 15 * 60_000;
+        const fallbackToken = `mtes_muxo_${crypto
+            .createHash("sha256")
+            .update(`${workspaceId || "global"}:${Math.floor(Date.now() / 600_000)}`)
+            .digest("hex")
+            .slice(0, 24)}`;
+        this.meterSessionToken = { token: fallbackToken, expiresAt };
+        return {
+            object: "v2.billing.meter_event_session",
+            authentication_token: fallbackToken,
+            created: new Date().toISOString(),
+            expires_at: new Date(expiresAt).toISOString(),
+            livemode: key.startsWith("sk_live_"),
+            source: "muxo_managed",
+        };
+    }
+    async recordMeterEvent(params) {
+        const identifier = params.identifier ||
+            `mev_${params.workspace.id}_${Date.now()}_${crypto.randomBytes(4).toString("hex")}`;
+        const dedupeKey = `${params.workspace.id}:${identifier}`;
+        const existing = this.meterEvents.find((e) => e.workspaceId === params.workspace.id && e.identifier === identifier);
+        if (existing || this.seenMeterIdentifiers.has(dedupeKey)) {
+            return {
+                recorded: false,
+                deduplicated: true,
+                event: existing || {
+                    identifier,
+                    event_name: params.event_name || "muxo_governed_tool_execution",
+                    timestamp: params.timestamp || new Date().toISOString(),
+                    workspaceId: params.workspace.id,
+                    stripe_customer_id: params.workspace.stripeCustomerId ||
+                        `cus_muxo_${params.workspace.id.slice(3, 11)}`,
+                    value: params.value,
+                    lane: params.lane || "composio_instant",
+                    tool_slug: params.tool_slug || "instant.web.search",
+                    livemode: false,
+                    source: "muxo_local_meter",
+                },
+            };
+        }
+        const eventName = params.event_name || "muxo_governed_tool_execution";
+        const timestamp = params.timestamp || new Date().toISOString();
+        const customerId = params.workspace.stripeCustomerId ||
+            `cus_muxo_${params.workspace.id.slice(3, 11)}`;
+        const value = Math.max(0, Number(params.value || 1));
+        const lane = params.lane || "composio_instant";
+        const toolSlug = params.tool_slug || "instant.web.search";
+        let source = "muxo_local_meter";
+        const key = this.getEffectiveStripeKey(params.workspace.id);
+        if (key) {
+            try {
+                if (!this.meterSessionToken ||
+                    this.meterSessionToken.expiresAt < Date.now() + 30_000) {
+                    await this.createMeterEventSession(params.workspace.id);
+                }
+                const base = this.config.stripeApiBaseUrl.replace(/\/v1\/?$/, "");
+                const streamHost = base.includes("127.0.0.1") || base.includes("localhost")
+                    ? base
+                    : "https://meter-events.stripe.com";
+                const res = await fetch(`${streamHost}/v2/billing/meter_event_stream`, {
+                    method: "POST",
+                    headers: {
+                        Authorization: `Bearer ${this.meterSessionToken?.token || key}`,
+                        "Stripe-Version": this.config.stripeProvisioningApiVersion || "2026-09-30.preview",
+                        "Content-Type": "application/json",
+                        Accept: "application/json",
+                    },
+                    body: JSON.stringify({
+                        events: [
+                            {
+                                event_name: eventName,
+                                identifier,
+                                timestamp,
+                                payload: {
+                                    stripe_customer_id: customerId,
+                                    value: String(value),
+                                    lane,
+                                    tool_slug: toolSlug,
+                                },
+                            },
+                        ],
+                    }),
+                    signal: AbortSignal.timeout(8_000),
+                });
+                if (res.ok || res.status === 202) {
+                    source = "stripe_v2_meter_stream";
+                }
+            }
+            catch {
+                source = "muxo_local_meter";
+            }
+        }
+        const record = {
+            identifier,
+            event_name: eventName,
+            timestamp,
+            workspaceId: params.workspace.id,
+            stripe_customer_id: customerId,
+            value,
+            lane,
+            tool_slug: toolSlug,
+            livemode: key.startsWith("sk_live_"),
+            source,
+        };
+        this.seenMeterIdentifiers.add(dedupeKey);
+        this.meterEvents.push(record);
+        if (this.meterEvents.length > 1000) {
+            this.meterEvents.shift();
+        }
+        return {
+            recorded: true,
+            deduplicated: false,
+            event: record,
+        };
+    }
+    listMeterEvents(workspaceId, limit = 50) {
+        const filtered = this.meterEvents
+            .filter((e) => e.workspaceId === workspaceId)
+            .slice(-Math.max(1, limit))
+            .reverse();
+        const byLane = {};
+        let totalValue = 0;
+        for (const evt of filtered) {
+            totalValue += evt.value;
+            byLane[evt.lane] = (byLane[evt.lane] || 0) + evt.value;
+        }
+        return {
+            events: filtered,
+            totalValue,
+            byLane,
+        };
+    }
 }