@muxoai/sdk 1.2.3 → 1.4.2

package/dist/types.d.ts

@@ -0,0 +1,593 @@
+export type RiskLevel = "read" | "write" | "admin" | "financial" | "provisioning" | "destructive";
+export type ProviderLane = "composio_sdk" | "composio_instant" | "stripe_projects";
+export type SubscriptionTier = "free" | "starter" | "pro";
+export type SubscriptionStatus = "none" | "active" | "trialing" | "past_due" | "unpaid" | "canceled" | "incomplete" | "comped";
+export interface WorkspaceBilling {
+    interval: "month" | "year" | null;
+    status: SubscriptionStatus;
+    cancelAtPeriodEnd: boolean;
+    /** When Stripe next renews or ends the subscription. */
+    currentPeriodEnd: string | null;
+    /** Monthly usage periods are counted from this moment. */
+    usagePeriodAnchor: string;
+    usagePeriodStart: string;
+    usagePeriodEnd: string;
+    /** usagePeriodStart of the last period whose plan credits were granted. */
+    creditsGrantedFor: string | null;
+    paymentFailedAt?: string | null;
+    /** Subscription whose start (fresh usage period and first credits) was already applied. */
+    startedSubscriptionId?: string | null;
+}
+export type LanguageMode = "non_technical" | "technical" | "hybrid";
+export interface HumanFriendlyExplanation {
+    headline: string;
+    preferred: string;
+    nonTechnical: string;
+    technical: string;
+    languageMode: LanguageMode;
+    customInstructions?: string[];
+}
+/**
+ * A structured handoff telling the caller (LLM or human) that a person must
+ * complete a step in the browser before the plan can proceed.
+ */
+export interface HumanHandoff {
+    kind: "approval" | "oauth" | "byok";
+    brand?: string;
+    url: string | null;
+    ctaLabel: string;
+    headline: string;
+    instructions: string;
+    markdownForUser?: string;
+    planId?: string;
+    provider?: string;
+}
+/**
+ * Machine-readable guidance for LLM harnesses on exactly which Muxo tool to
+ * call next once a handoff or gate clears.
+ */
+export interface LlmGuidance {
+    summary: string;
+    nextToolCalls: Array<{
+        tool: string;
+        input: Record<string, unknown>;
+        when: string;
+    }>;
+}
+export type WorkspaceRole = "owner" | "admin" | "operator" | "member";
+export type ParameterRuleOperator = "equals" | "must_equal" | "not_equals" | "contains" | "not_contains" | "starts_with" | "must_start_with" | "ends_with" | "must_end_with" | "domain_in" | "domain_not_in" | "max_number" | "min_number" | "gt" | "gte" | "lt" | "lte" | "in" | "not_in" | "regex";
+export type ParameterRuleAction = "block" | "require_approval" | "allow" | "auto_approve";
+export interface ParameterPolicyRule {
+    id: string;
+    toolPattern?: string;
+    parameter: string;
+    operator: ParameterRuleOperator;
+    value: string | number | string[];
+    unit?: "usd" | "cents" | "credits" | "raw";
+    action: ParameterRuleAction;
+    elseAction?: ParameterRuleAction;
+    description: string;
+    source?: "deterministic" | "llm" | "mcp_harness" | "user";
+}
+export interface GovernancePolicy {
+    mode: "monitor" | "enforce";
+    requireApprovalFor: RiskLevel[];
+    allowInstantWallet: boolean;
+    allowProvisioning: boolean;
+    maxCreditsPerRun: number;
+    blockedToolSlugs?: string[];
+    parameterRules?: ParameterPolicyRule[];
+    executionRing?: 0 | 1 | 2 | 3;
+    killSwitchActive?: boolean;
+    killSwitchReason?: string | null;
+    blockDestructiveSql?: boolean;
+    naturalLanguageRules?: string[];
+    languageMode?: LanguageMode;
+    customInstructions?: string[];
+}
+export interface User {
+    id: string;
+    email: string;
+    name: string;
+    workspaceId: string;
+    role: WorkspaceRole;
+    createdAt: string;
+}
+export interface WorkspaceMembership {
+    id: string;
+    workspaceId: string;
+    userId: string;
+    role: WorkspaceRole;
+    teamName: string | null;
+    joinedViaKeyId?: string | null;
+    joinedVia?: "owner" | "created" | "api_key" | "team_key" | "invite" | "claim" | string;
+    apiKeyId?: string | null;
+    createdAt: string;
+}
+export interface WorkspaceSummary {
+    id: string;
+    name: string;
+    slug: string;
+    tier: SubscriptionTier;
+    creditsBalance: number;
+    monthlyActionsUsed: number;
+    monthlyActionsLimit: number;
+    role: WorkspaceRole;
+    teamName: string | null;
+    joinedVia?: "owner" | "created" | "api_key" | "team_key" | "invite" | "claim" | string;
+    isCurrent: boolean;
+    createdAt: string;
+}
+export interface TeamOnboardingKit {
+    ok?: boolean;
+    mode: "shared_workspace" | "dedicated_workspace";
+    workspace: Workspace | Pick<Workspace, "id" | "name" | "slug" | "tier" | "creditsBalance">;
+    teamName: string;
+    role: WorkspaceRole;
+    apiKey: string;
+    keyRecord: ApiKeyRecord;
+    claimUrl?: string | null;
+    consoleUrl?: string;
+    consoleJoinUrl?: string;
+    mcpEndpoint?: string;
+    cliSetupCommand: string;
+    mcpConfig?: Record<string, unknown>;
+    mcpConfigSnippet?: string;
+    instructions: string[];
+}
+export interface Workspace {
+    id: string;
+    name: string;
+    slug: string;
+    ownerUserId: string;
+    tier: SubscriptionTier;
+    monthlyActionsLimit: number;
+    monthlyActionsUsed: number;
+    creditsBalance: number;
+    stripeCustomerId: string | null;
+    stripeSubscriptionId: string | null;
+    stripeConnectedAccountId?: string | null;
+    billing?: WorkspaceBilling;
+    projectsEnvName: string;
+    policy: GovernancePolicy;
+    createdAt: string;
+    updatedAt: string;
+}
+export interface ApiKeyRecord {
+    id: string;
+    workspaceId: string;
+    name: string;
+    keyPrefix: string;
+    environment: "live" | "test";
+    scopes: string[];
+    teamName?: string | null;
+    role?: WorkspaceRole;
+    createdByEmail?: string | null;
+    lastUsedAt: string | null;
+    revokedAt: string | null;
+    createdAt: string;
+}
+export interface MuxoTool {
+    slug: string;
+    upstreamSlug: string;
+    name: string;
+    description: string;
+    lane: ProviderLane;
+    providerSlug: string;
+    providerName: string;
+    categories: string[];
+    riskLevel: RiskLevel;
+    requiresAuth: boolean;
+    creditCost: number;
+    billingMode: "customer_oauth" | "customer_byok" | "provider_wallet" | "resource_provisioning";
+    inputSchema: Record<string, unknown>;
+    llmContextUrl?: string;
+    providerUrl?: string;
+    metadata?: Record<string, unknown>;
+}
+export type ToolDescriptor = MuxoTool;
+export interface ConnectionRecord {
+    id: string;
+    workspaceId: string;
+    lane: ProviderLane;
+    providerSlug: string;
+    providerName: string;
+    status: "active" | "pending" | "expired" | "disconnected";
+    externalAccountId: string | null;
+    redirectUrl: string | null;
+    metadata: Record<string, unknown>;
+    updatedAt: string;
+    createdAt: string;
+}
+export interface ProvisionedResource {
+    id: string;
+    workspaceId: string;
+    resourceName: string;
+    providerSlug: string;
+    providerName: string;
+    serviceSlug: string;
+    planSlug: string | null;
+    status: "active" | "provisioning" | "failed" | "removed";
+    envVarKeys: string[];
+    externalResourceId: string | null;
+    metadata: Record<string, unknown>;
+    createdAt: string;
+    updatedAt: string;
+}
+export interface GovernanceDecisionRecord {
+    id: string;
+    sdk: "@microsoft/agent-governance-sdk";
+    sdkVersion: string;
+    policyId: string;
+    mode: "monitor" | "enforce";
+    agentDid: string;
+    agentPublicKey: string;
+    actorId: string;
+    workspaceId: string;
+    action: string;
+    riskLevel: RiskLevel;
+    decision: "allow" | "deny" | "require_approval";
+    verdict: "allow" | "deny" | "escalate";
+    reason: string;
+    matchedRule: string | null;
+    securityScan: {
+        safe: boolean;
+        riskLevel: string;
+        findingsCount: number;
+        findings: Array<{
+            category: string;
+            severity: string;
+            description: string;
+        }>;
+    };
+    auditEntry: {
+        timestamp: string;
+        agentId: string;
+        action: string;
+        decision: "allow" | "deny";
+        hash: string;
+        previousHash: string;
+        chainVerified: boolean;
+    };
+    protocolFacets?: {
+        sql?: {
+            verb: string;
+            target: string;
+            tables: string;
+            functions: string;
+            destructive?: boolean;
+        };
+        k8s?: {
+            verb: string;
+            resource: string;
+            namespace: string;
+            name: string;
+            subresource: string;
+        };
+        infra?: {
+            provider: string;
+            service: string;
+            action: string;
+            destructive: boolean;
+        };
+    };
+    ringEnforcement?: {
+        agentRing: number;
+        requiredRing: number;
+        allowed: boolean;
+        ringLabel: string;
+    };
+    trustScore?: {
+        overall: number;
+        tier: "Untrusted" | "Provisional" | "Trusted" | "Verified";
+        reliability: number;
+        consistency: number;
+    };
+    contextPoisoning?: {
+        safe: boolean;
+        riskLevel: "none" | "low" | "medium" | "high" | "critical";
+        findingsCount: number;
+        findings: Array<{
+            patternId: string;
+            patternName: string;
+            severity: string;
+            description: string;
+        }>;
+    };
+    killSwitch?: {
+        active: boolean;
+        killedAt?: string | null;
+        reason?: string | null;
+    };
+    ed25519Signature: string;
+    signature: string;
+    bindingHash: string;
+    decidedAt: string;
+    explanation?: HumanFriendlyExplanation;
+}
+export type MemoryRecordKind = "fact" | "preference" | "resource_note" | "operator_note" | "execution_outcome" | "resource_topology" | "policy_decision";
+export interface TemporalGraphFact {
+    id: string;
+    workspaceId: string;
+    subject: string;
+    predicate: string;
+    object: string;
+    summary: string;
+    confidence: number;
+    validFrom: string;
+    validTo: string | null;
+    supersededById?: string | null;
+    sourceKind: MemoryRecordKind | "system" | "manual";
+    sourceReferenceId?: string | null;
+    metadata: Record<string, unknown>;
+    createdAt: string;
+}
+export interface MemoryGraphNode {
+    id: string;
+    kind: "workspace" | "entity" | "preference" | "guardrail" | "connection" | "resource" | "tool" | "memory";
+    label: string;
+    summary: string;
+    status: "active" | "historical";
+    metadata?: Record<string, unknown>;
+}
+export interface MemoryGraphEdge {
+    id: string;
+    source: string;
+    target: string;
+    subject?: string;
+    object?: string;
+    predicate: string;
+    summary: string;
+    confidence: number;
+    status: "active" | "historical";
+    validFrom: string;
+    validTo: string | null;
+    supersededById: string | null;
+    sourceKind: TemporalGraphFact["sourceKind"];
+    sourceReferenceId: string | null;
+}
+export interface MemoryKnowledgeGraph {
+    workspaceId: string;
+    workspaceSlug: string;
+    namespace: string;
+    generatedAt: string;
+    query: string | null;
+    nodes: MemoryGraphNode[];
+    edges: MemoryGraphEdge[];
+    activeEdges: MemoryGraphEdge[];
+    historicalEdges: MemoryGraphEdge[];
+    stats: {
+        nodesCount: number;
+        activeEdgesCount: number;
+        historicalEdgesCount: number;
+        memoriesCount: number;
+        resourcesCount: number;
+        connectionsCount: number;
+    };
+    mermaid: string;
+    explanation: HumanFriendlyExplanation;
+}
+export interface MemoryContextSummary {
+    enabled: boolean;
+    namespace: string;
+    fundingSource?: "muxo_funded" | "customer_byok_supermemory" | "local_fallback";
+    staticFacts: string[];
+    dynamicContext: string[];
+    recalledMemories: Array<{
+        documentId: string;
+        title: string;
+        snippet: string;
+        similarity: number;
+        createdAt?: string;
+    }>;
+    formattedPromptContext: string;
+    profileMarkdown?: string;
+    profile: {
+        static: string[];
+        dynamic: string[];
+        preferences: string[];
+    };
+    relevantMemories: Array<{
+        documentId: string;
+        title: string;
+        snippet: string;
+        similarity: number;
+        createdAt?: string;
+    }>;
+    temporalFacts?: TemporalGraphFact[];
+    activeDefaults?: Record<string, unknown>;
+    autoFilledInput?: Record<string, unknown>;
+    activeGuardrails?: string[];
+    contextPoisoningScan?: {
+        safe: boolean;
+        riskLevel: "none" | "low" | "medium" | "high" | "critical";
+        findingsCount: number;
+    };
+    explanation?: HumanFriendlyExplanation;
+}
+export interface WorkspaceMemoryRecord {
+    id: string;
+    workspaceId: string;
+    namespace: string;
+    documentId: string;
+    title: string;
+    content: string;
+    kind: MemoryRecordKind;
+    metadata: Record<string, unknown>;
+    fundingSource?: string;
+    createdAt: string;
+}
+export interface ByokKeyRecord {
+    provider: string;
+    providerSlug?: string;
+    category: "llm" | "supplier";
+    envVarName: string;
+    keyPreview: string;
+    configured: boolean;
+    updatedAt: string;
+}
+export interface SupplierSettlement {
+    fundingMode: "muxo_funded" | "byok";
+    supplier: ProviderLane;
+    supplierName: string;
+    upstreamProvider: string;
+    userChargeCredits: number;
+    userRetailChargeCents: number;
+    supplierWholesalePayableCents: number;
+    muxoNetMarginCents: number;
+    settlementStatus: "settled_by_muxo_master_wallet" | "planned_muxo_master_wallet" | "settled_by_customer_byok" | "planned_customer_byok";
+    masterAccountRef: string;
+}
+export interface SupplierSettlementSummary {
+    workspaceId: string;
+    fundingModel: "user_pays_muxo_muxo_pays_suppliers";
+    activeFundingMode?: "muxo_funded" | "byok_hybrid";
+    byokProviders?: string[];
+    creditPriceCents: number;
+    totalCreditsPurchasedOrGranted: number;
+    totalCreditsConsumed: number;
+    currentCreditsBalance: number;
+    totalUserRetailSpendCents: number;
+    totalSupplierWholesalePaidCents: number;
+    totalMuxoNetMarginCents: number;
+    bySupplier: Record<ProviderLane, {
+        runsCount: number;
+        creditsConsumed: number;
+        userRetailSpendCents: number;
+        supplierWholesalePaidCents: number;
+        muxoNetMarginCents: number;
+    }>;
+    masterWalletProtection?: {
+        status: "healthy" | "failover_active";
+        zeroChargeOnFailure: boolean;
+        instantFailoverMode: "zero_cost_native_edge";
+        paidProvisioningPolicy: "muxo_master_wallet_or_customer_stripe_byok";
+        retailToWholesaleCoverageRatio: number;
+    };
+}
+export interface HumanHandoffDescriptor {
+    required: boolean;
+    kind: "none" | "oauth_connection" | "human_approval" | "oauth_and_approval";
+    status: "ready" | "awaiting_oauth" | "awaiting_approval" | "awaiting_oauth_and_approval" | "connected" | "approved" | "rejected";
+    headline: string;
+    markdownForUser: string;
+    agentNextToolCall: {
+        tool: string;
+        arguments: Record<string, unknown>;
+        description: string;
+    };
+    actionUrl: string | null;
+    approvalUrl: string | null;
+    oauthRedirectUrl: string | null;
+    consoleUrl: string;
+}
+export interface ActionPlan {
+    id: string;
+    workspaceId: string;
+    actorId: string;
+    toolSlug: string;
+    upstreamSlug: string;
+    lane: ProviderLane;
+    riskLevel: RiskLevel;
+    input: Record<string, unknown>;
+    reason: string;
+    creditCost: number;
+    approvalStatus: "auto_approved" | "pending_approval" | "approved" | "rejected" | "executed";
+    approvedBy: string | null;
+    approvedAt: string | null;
+    runId: string | null;
+    decisionRecord?: GovernanceDecisionRecord | null;
+    memoryContext?: MemoryContextSummary | null;
+    supplierSettlement?: SupplierSettlement | null;
+    surfaceVersion?: string;
+    surfaceAudience?: string;
+    surfaceConnectionId?: string | null;
+    surfaceContext?: Array<{
+        recordId: string;
+        revision: number;
+        contentHash: string;
+    }>;
+    surfaceFunding?: {
+        resource_id: string;
+        mode: "customer_funded" | "muxo_funded";
+    } | null;
+    surfaceOperationId?: string;
+    createdAt: string;
+    expiresAt: string;
+}
+export interface ExecutionRun {
+    id: string;
+    planId: string;
+    workspaceId: string;
+    actorId: string;
+    toolSlug: string;
+    lane: ProviderLane;
+    riskLevel: RiskLevel;
+    status: "queued" | "running" | "succeeded" | "failed" | "cancelled";
+    input: Record<string, unknown>;
+    output: Record<string, unknown> | null;
+    error: string | null;
+    errorMessage?: string | null;
+    actionsMetered: number;
+    creditsMetered: number;
+    durationMs: number | null;
+    receiptId: string | null;
+    startedAt: string;
+    completedAt: string | null;
+}
+export type AgenticReceiptActionType = "ToolCall" | "ModelInference" | "GpuWorkload" | "RagRetrieval" | "ApiCall" | "DistributedJob";
+export interface PortableAgenticReceipt {
+    version: string;
+    receipt_id: string;
+    agent_id: string;
+    task_id: string;
+    action_type: AgenticReceiptActionType;
+    tool_name: string | null;
+    model_id: string | null;
+    input_hash: string;
+    output_hash: string;
+    started_at: string;
+    completed_at: string;
+    latency_ms: number;
+    nonce: string;
+    previous_receipt_hash: string | null;
+    receipt_hash: string;
+    signature_algorithm: "Ed25519";
+    public_key_hex: string;
+    signature_hex: string;
+}
+export interface ExecutionReceipt {
+    id: string;
+    runId: string;
+    planId: string;
+    workspaceId: string;
+    actorId: string;
+    toolSlug: string;
+    lane: ProviderLane;
+    riskLevel: RiskLevel;
+    status: "succeeded" | "failed" | "cancelled";
+    actionsMetered: number;
+    creditsMetered: number;
+    inputHash: string;
+    outputHash: string;
+    prevReceiptHash: string;
+    receiptHash: string;
+    signature: string;
+    decisionRecord?: GovernanceDecisionRecord | null;
+    agenticReceipt?: PortableAgenticReceipt | null;
+    supplierSettlement?: SupplierSettlement | null;
+    issuedAt: string;
+    explanation?: HumanFriendlyExplanation;
+}
+export interface LedgerEntry {
+    id: string;
+    workspaceId: string;
+    kind: "plan_grant" | "credit_topup" | "run_deduction" | "subscription_upgrade" | "plan_change" | "refund" | "manual_adjustment";
+    actionsDelta: number;
+    creditsDelta: number;
+    balanceAfter: number;
+    referenceId: string | null;
+    description: string;
+    supplierSettlement?: SupplierSettlement | null;
+    createdAt: string;
+}

package/dist/types.js

@@ -0,0 +1 @@
+export {};

package/dist/ui/console-html.d.ts

@@ -0,0 +1,64 @@
+export type ConsoleView = "overview" | "catalog" | "setup" | "workspaces" | "activity" | "billing" | "login" | "signup";
+/** Every path that serves the console shell, mapped to the view it opens. */
+export declare const CONSOLE_ROUTES: Readonly<Record<string, ConsoleView>>;
+export declare function isConsolePath(pathname: string): boolean;
+export declare function renderConsoleHtml(): string;
+export declare function renderLandingHtml(): string;
+export interface OAuthConsentOptions {
+    error?: string;
+    clientName?: string;
+    redirectOrigin?: string;
+    clerk?: {
+        publishableKey: string;
+        frontendApi: string;
+    } | null;
+    request?: Record<string, string>;
+    /** Renders the workspace-claim variant, which posts to `action` instead of /oauth/authorize. */
+    claim?: {
+        workspaceName: string;
+        targetEmail: string;
+        action: string;
+        cancelUrl: string;
+    };
+}
+/** Consent screen for MCP clients (ChatGPT, Claude, CLIs) asking to use a Muxo workspace. */
+export declare function renderOAuthConsentHtml(opts: OAuthConsentOptions): string;
+export interface ApprovalPageOptions {
+    planId: string;
+    clerk?: {
+        publishableKey: string;
+        frontendApi: string;
+    } | null;
+}
+/** One-click approval screen for plans held by workspace guardrails (`/approve/:planId`). */
+export declare function renderApprovalPageHtml(opts: ApprovalPageOptions): string;
+export interface OAuthConnectPageField {
+    name: string;
+    type?: string;
+    label?: string;
+    description?: string;
+    required?: boolean;
+    default?: string | null;
+}
+export interface OAuthConnectPageOptions {
+    token: string;
+    toolkitSlug: string;
+    toolkitName: string;
+    workspaceId?: string;
+    authMode?: string;
+    status?: string;
+    callbackUrl?: string | null;
+    expectedInputFields?: OAuthConnectPageField[];
+    error?: string | null;
+}
+/** Muxo-branded OAuth connection handoff screen (`/oauth/connect/:token`). */
+export declare function renderOAuthConnectPageHtml(opts: OAuthConnectPageOptions): string;
+export interface OAuthCallbackPageOptions {
+    providerSlug: string;
+    providerName: string;
+    status: string;
+    workspaceId: string;
+    externalAccountId?: string | null;
+}
+/** Muxo-branded OAuth callback completion screen (`/oauth/callback`). */
+export declare function renderOAuthCallbackPageHtml(opts: OAuthCallbackPageOptions): string;