@muxoai/sdk 1.2.3 → 1.4.2

package/dist/engine.d.ts

@@ -0,0 +1,465 @@
+import type { MuxoConfig } from "./config.js";
+import { type DurableWorkflow } from "./durable-workflow.js";
+import { type NaturalLanguageResolution } from "./nl.js";
+import { describePolicyInPlainEnglish, type GuardrailCompileOptions, type LlmPolicyAndGovernanceBrief, type ParsedNaturalLanguageGuardrail, type PolicySimulationResult } from "./policy.js";
+import { ComposioInstantAdapter } from "./providers/composio-instant.js";
+import { ComposioSdkAdapter } from "./providers/composio-sdk.js";
+import { MicrosoftGovernanceAdapter } from "./providers/microsoft-governance.js";
+import { StripeBillingAdapter } from "./providers/stripe-billing.js";
+import { StripeProjectsAdapter } from "./providers/stripe-projects.js";
+import { SupermemoryAdapter, type ActiveMemoryDefaults } from "./providers/supermemory.js";
+import type { MuxoStore } from "./store.js";
+import type { ActionPlan, ConnectionRecord, ExecutionReceipt, ExecutionRun, GovernanceDecisionRecord, HumanFriendlyExplanation, HumanHandoff, LanguageMode, LlmGuidance, MemoryContextSummary, MemoryKnowledgeGraph, MuxoTool, PortableAgenticReceipt, ProviderLane, RiskLevel, User, Workspace, WorkspaceMemoryRecord } from "./types.js";
+export type RunContextPayload = {
+    workspaceId: string;
+    workspaceSlug: string;
+    projectsEnvironment: string;
+    policy: Workspace["policy"];
+    plainEnglishPolicy: ReturnType<typeof describePolicyInPlainEnglish>;
+    languageMode: LanguageMode;
+    customInstructions: string[];
+    activeDefaults: ActiveMemoryDefaults;
+    activeGuardrails: string[];
+    creditsBalance: number;
+    monthlyActionsRemaining: number;
+    provisionedResources: ReturnType<MuxoStore["listResources"]>;
+    environmentVariablesRedacted: Record<string, string>;
+    supermemoryBrain: MemoryContextSummary;
+    temporalFacts: NonNullable<MemoryContextSummary["temporalFacts"]>;
+    governance: ReturnType<MicrosoftGovernanceAdapter["getStatus"]>;
+    trustScore: ReturnType<MicrosoftGovernanceAdapter["getWorkspaceTrustScore"]>;
+    llmSystemPrompt: string;
+    explanation: HumanFriendlyExplanation;
+    envPullHint: string;
+};
+export interface ExecutionContext {
+    user: User;
+    workspace: Workspace;
+    actorId: string;
+    authType: "session" | "api_key";
+}
+export declare class MuxoEngine {
+    readonly config: MuxoConfig;
+    readonly store: MuxoStore;
+    readonly composioSdk: ComposioSdkAdapter;
+    readonly composioInstant: ComposioInstantAdapter;
+    readonly stripeProjects: StripeProjectsAdapter;
+    readonly stripeBilling: StripeBillingAdapter;
+    readonly governance: MicrosoftGovernanceAdapter;
+    readonly supermemory: SupermemoryAdapter;
+    private readonly durableWorkflows;
+    constructor(config: MuxoConfig, store: MuxoStore);
+    getProfile(ctx: ExecutionContext): Record<string, unknown>;
+    getOrganization(ctx: ExecutionContext): Record<string, unknown>;
+    searchTools(params: {
+        query?: string;
+        lane?: ProviderLane | "all";
+        riskLevel?: RiskLevel;
+        limit?: number;
+    }): Promise<{
+        tools: MuxoTool[];
+        total: number;
+    }>;
+    listAllCatalogTools(): Promise<MuxoTool[]>;
+    inspectTool(slug: string): Promise<MuxoTool>;
+    connectionStatus(ctx: ExecutionContext, params?: {
+        provider?: string;
+        syncLive?: boolean;
+    }): Promise<Record<string, unknown>>;
+    getHostedSiteHtml(slug: string, filePath?: string): string | null;
+    startConnection(ctx: ExecutionContext, params: {
+        provider: string;
+        lane?: ProviderLane;
+        callbackUrl?: string;
+    }): Promise<ConnectionRecord & {
+        message: string;
+        callbackUrl?: string;
+    }>;
+    waitForConnection(ctx: ExecutionContext, params: {
+        provider: string;
+        timeoutSeconds?: number;
+        pollIntervalMs?: number;
+    }): Promise<{
+        ok: true;
+        connected: boolean;
+        ready: boolean;
+        timedOut: boolean;
+        provider: string;
+        status: ConnectionRecord["status"];
+        connection: ConnectionRecord;
+        redirectUrl: string | null;
+        polledAttempts: number;
+        elapsedMs: number;
+        message: string;
+    }>;
+    handleOAuthCallback(params: {
+        workspaceId: string;
+        provider: string;
+        connectedAccountId?: string;
+        status?: string;
+    }): Promise<{
+        ok: boolean;
+        workspaceId: string;
+        providerSlug: string;
+        providerName: string;
+        status: ConnectionRecord["status"];
+        externalAccountId: string | null;
+    }>;
+    planAction(ctx: ExecutionContext, params: {
+        toolSlug: string;
+        input?: Record<string, unknown>;
+        reason?: string;
+        fundingMode?: "muxo_funded" | "byok";
+    }): Promise<{
+        plan: ActionPlan;
+        tool: MuxoTool;
+        decisionRecord: GovernanceDecisionRecord;
+        memoryContext: MemoryContextSummary;
+        authHandoff?: {
+            required: boolean;
+            provider: string;
+            status: ConnectionRecord["status"];
+            redirectUrl: string | null;
+            externalAccountId: string | null;
+            instructions: string;
+        };
+        humanHandoff?: HumanHandoff;
+        llmGuidance: LlmGuidance;
+        nextStep: string;
+    }>;
+    getPlan(ctx: ExecutionContext, planId: string): ActionPlan;
+    waitForPlanApproval(ctx: ExecutionContext, params: {
+        planId: string;
+        timeoutSeconds?: number;
+        pollIntervalMs?: number;
+    }): Promise<{
+        ok: true;
+        approved: boolean;
+        rejected: boolean;
+        timedOut: boolean;
+        waitedForApproval: true;
+        approvalStatus: ActionPlan["approvalStatus"];
+        approvalUrl: string;
+        waitedMs: number;
+        plan: ActionPlan;
+    }>;
+    approvePlan(ctx: ExecutionContext, planId: string, decision?: "approved" | "rejected"): ActionPlan;
+    private buildApprovalHandoff;
+    private buildOAuthHandoff;
+    private buildPlanLlmGuidance;
+    private enrichMemoryContext;
+    getRunContext(ctx: ExecutionContext, query?: string): Promise<{
+        explanation: HumanFriendlyExplanation;
+        plainEnglishPolicy: ReturnType<typeof describePolicyInPlainEnglish>;
+        activeDefaults: ActiveMemoryDefaults;
+        activeGuardrails: string[];
+        [key: string]: unknown;
+    }>;
+    getMemoryOverview(ctx: ExecutionContext, query?: string): Promise<{
+        enabled: boolean;
+        namespace: string;
+        fundingSource: string;
+        context: MemoryContextSummary;
+        activeDefaults: ActiveMemoryDefaults;
+        activeGuardrails: string[];
+        explanation: HumanFriendlyExplanation;
+        recentMemories: WorkspaceMemoryRecord[];
+        memories: WorkspaceMemoryRecord[];
+        temporalFacts: ReturnType<MuxoStore["listTemporalFacts"]>;
+        historicalFacts: ReturnType<MuxoStore["listTemporalFacts"]>;
+    }>;
+    addWorkspaceMemory(ctx: ExecutionContext, params: {
+        title: string;
+        content: string;
+        kind?: WorkspaceMemoryRecord["kind"];
+        metadata?: Record<string, unknown>;
+        subject?: string;
+        predicate?: string;
+        object?: string;
+    }): Promise<WorkspaceMemoryRecord>;
+    deleteWorkspaceMemory(ctx: ExecutionContext, idOrDocId: string): Promise<{
+        deleted: boolean;
+        record: WorkspaceMemoryRecord | null;
+    }>;
+    forgetWorkspaceMemoryMatching(ctx: ExecutionContext, query: string): Promise<{
+        query: string;
+        deletedLocalCount: number;
+        invalidatedFactsCount: number;
+        deletedRemoteIds: string[];
+        deletedMemories: WorkspaceMemoryRecord[];
+        invalidatedFacts: ReturnType<MuxoStore["listTemporalFacts"]>;
+    }>;
+    /**
+     * Synthesizes a Bi-Temporal Knowledge Graph (entities, active relationships, superseded historical relationships,
+     * Mermaid diagram, and human + technical explanations) directly from SQLite temporal_facts, memories, resources, and connections.
+     */
+    getMemoryGraph(ctx: ExecutionContext, query?: string): Promise<MemoryKnowledgeGraph>;
+    activateWorkspaceKillSwitch(ctx: ExecutionContext, params: {
+        reason: string;
+        action?: "terminate" | "quarantine" | "suspend";
+    }): Promise<Record<string, unknown>>;
+    resumeWorkspaceKillSwitch(ctx: ExecutionContext): Record<string, unknown>;
+    executePlanForRisk(ctx: ExecutionContext, planId: string, expectedRisk: RiskLevel): Promise<{
+        run: ExecutionRun;
+        receipt: ExecutionReceipt;
+    }>;
+    getRun(ctx: ExecutionContext, runId: string): ExecutionRun;
+    cancelRun(ctx: ExecutionContext, runId: string, reason?: string): {
+        ok: true;
+        cancelled: true;
+        alreadyCancelled: boolean;
+        previousStatus: ExecutionRun["status"];
+        run: ExecutionRun;
+        receipt: ExecutionReceipt;
+        signatureValid: boolean;
+        message: string;
+    };
+    explainReceipt(receipt: ExecutionReceipt, verification: {
+        signatureValid: boolean;
+        governanceSignatureValid: boolean;
+        agenticReceiptValid?: boolean;
+    }, policy?: Partial<Workspace["policy"]> | null, languageMode?: LanguageMode): HumanFriendlyExplanation;
+    getReceipt(ctx: ExecutionContext, receiptOrRunId: string): {
+        receipt: ExecutionReceipt;
+        agenticReceipt: PortableAgenticReceipt;
+        signatureValid: boolean;
+        governanceSignatureValid: boolean;
+        agenticReceiptValid: boolean;
+        explanation: HumanFriendlyExplanation;
+    };
+    listReceipts(ctx: ExecutionContext, limit?: number): {
+        receipts: Array<ExecutionReceipt & {
+            agenticReceipt: PortableAgenticReceipt;
+            signatureValid: boolean;
+            governanceSignatureValid: boolean;
+            agenticReceiptValid: boolean;
+            explanation: HumanFriendlyExplanation;
+        }>;
+        total: number;
+        explanation: HumanFriendlyExplanation;
+    };
+    /**
+     * Verifies the entire cryptographic receipt chain (`prevReceiptHash` -> `receiptHash`,
+     * HMAC vault signatures, Ed25519 Governance DecisionRecords, and portable Ed25519 AgenticReceipts).
+     */
+    verifyReceiptChain(ctx: ExecutionContext, limit?: number): {
+        ok: true;
+        valid: boolean;
+        workspaceId: string;
+        agentDid: string;
+        publicKeyHex: string;
+        chainValid: boolean;
+        hashLinksValid: boolean;
+        allHmacValid: boolean;
+        allEd25519AgenticValid: boolean;
+        allGovernanceValid: boolean;
+        totalReceipts: number;
+        totalChecked: number;
+        validCount: number;
+        brokenLinks: Array<{
+            receiptId: string;
+            runId: string;
+            reason: string;
+        }>;
+        genesisHash: string;
+        headReceiptHash: string;
+        links: Array<{
+            index: number;
+            receiptId: string;
+            runId: string;
+            toolSlug: string;
+            prevReceiptHash: string;
+            receiptHash: string;
+            hashLinkValid: boolean;
+            hmacValid: boolean;
+            ed25519AgenticValid: boolean;
+            governanceValid: boolean;
+            issuedAt: string;
+        }>;
+        explanation: HumanFriendlyExplanation;
+    };
+    getGovernanceOverview(ctx: ExecutionContext): {
+        workspaceId: string;
+        killSwitch: {
+            active: boolean;
+            reason: string | null;
+        };
+        governance: ReturnType<MicrosoftGovernanceAdapter["getStatus"]>;
+        trustScore: ReturnType<MicrosoftGovernanceAdapter["getWorkspaceTrustScore"]>;
+        policy: Workspace["policy"];
+        plainEnglish: ReturnType<typeof describePolicyInPlainEnglish>;
+        llmPolicyBrief: LlmPolicyAndGovernanceBrief;
+        explanation: HumanFriendlyExplanation;
+    };
+    resetWorkspaceGuardrails(ctx: ExecutionContext): {
+        ok: true;
+        action: "reset_guardrails";
+        workspace: Workspace;
+        policy: Workspace["policy"];
+        plainEnglish: ReturnType<typeof describePolicyInPlainEnglish>;
+        llmPolicyBrief: LlmPolicyAndGovernanceBrief;
+        explanation: HumanFriendlyExplanation;
+    };
+    checkToolPolicy(ctx: ExecutionContext, params: {
+        toolSlug: string;
+        input?: Record<string, unknown>;
+    }): Promise<PolicySimulationResult>;
+    setKillSwitch(ctx: ExecutionContext, active: boolean, reason?: string): Workspace;
+    scanForContextPoisoning(workspaceId: string, text: string): {
+        poisoned: boolean;
+        severity: string;
+        matchedPatterns: string[];
+        findingsCount: number;
+        integrityValid: boolean;
+    };
+    getGuardrailsSummary(ctx: ExecutionContext): {
+        workspaceId: string;
+        policy: Workspace["policy"];
+        plainEnglish: ReturnType<typeof describePolicyInPlainEnglish>;
+        llmPolicyBrief: LlmPolicyAndGovernanceBrief;
+        activeDefaults: ActiveMemoryDefaults;
+        activeGuardrails: string[];
+    };
+    applyNaturalLanguageGuardrail(ctx: ExecutionContext, prompt: string, options?: GuardrailCompileOptions): Promise<{
+        ok: boolean;
+        workspace: Workspace;
+        guardrail: ParsedNaturalLanguageGuardrail;
+        plainEnglish: ReturnType<typeof describePolicyInPlainEnglish>;
+        llmPolicyBrief: LlmPolicyAndGovernanceBrief;
+        memoryRecord?: WorkspaceMemoryRecord;
+    }>;
+    doNaturalLanguage(ctx: ExecutionContext, params: {
+        prompt: string;
+        input?: Record<string, unknown>;
+        autoApprove?: boolean;
+        dryRun?: boolean;
+        planOnly?: boolean;
+        fundingMode?: "muxo_funded" | "byok";
+    }): Promise<{
+        ok: boolean;
+        executed: boolean;
+        status: "executed" | "planned_dry_run" | "awaiting_approval" | "awaiting_oauth_connection" | "missing_inputs" | "guardrail_applied" | "memory_saved" | "memory_forgotten" | "memory_recalled" | "memory_graph" | "governance_updated" | "governance_scanned" | "governance_status" | "context_inspected" | "receipt_explained" | "receipt_chain_verified" | "unresolved";
+        intent: NaturalLanguageResolution;
+        resolution: NaturalLanguageResolution;
+        plan?: ActionPlan;
+        run?: ExecutionRun;
+        receipt?: ExecutionReceipt;
+        receiptVerification?: {
+            receipt: ExecutionReceipt;
+            agenticReceipt?: PortableAgenticReceipt;
+            signatureValid: boolean;
+            governanceSignatureValid: boolean;
+            agenticReceiptValid?: boolean;
+            explanation: HumanFriendlyExplanation;
+        };
+        receiptsList?: ReturnType<MuxoEngine["listReceipts"]>;
+        receiptChain?: ReturnType<MuxoEngine["verifyReceiptChain"]>;
+        guardrail?: ParsedNaturalLanguageGuardrail;
+        plainEnglishGuardrails?: ReturnType<typeof describePolicyInPlainEnglish>;
+        memoryRecord?: WorkspaceMemoryRecord;
+        memoryOverview?: Awaited<ReturnType<MuxoEngine["getMemoryOverview"]>>;
+        memoryGraph?: MemoryKnowledgeGraph;
+        deletedMemoryId?: string;
+        governanceStatus?: ReturnType<MuxoEngine["getGovernanceOverview"]>;
+        poisoningScan?: ReturnType<MuxoEngine["scanForContextPoisoning"]>;
+        runContext?: Awaited<ReturnType<MuxoEngine["getRunContext"]>>;
+        explanation?: HumanFriendlyExplanation;
+        activeDefaults?: ActiveMemoryDefaults;
+        activeMemoryDefaults?: ActiveMemoryDefaults;
+        memoryAutoFilled?: Record<string, unknown>;
+        authHandoff?: Record<string, unknown>;
+        humanHandoff?: HumanHandoff;
+        llmGuidance?: LlmGuidance;
+        byokPrompt?: {
+            needed: boolean;
+            provider: string;
+            envVarName: string;
+            cliCommand: string;
+            message: string;
+        };
+        humanMessage: string;
+    }>;
+    /**
+     * Parallel Governed Multi-Tool Batch Execution (`COMPOSIO_MULTI_EXECUTE_TOOL` pattern).
+     * Evaluates governance & policy across every item, then executes all approved plans concurrently.
+     */
+    executeBatchPlans(ctx: ExecutionContext, params: {
+        items: Array<{
+            toolSlug: string;
+            input: Record<string, unknown>;
+            reason: string;
+        }>;
+        autoApprove?: boolean;
+    }): Promise<{
+        batchId: string;
+        totalRequested: number;
+        succeededCount: number;
+        blockedOrPendingCount: number;
+        results: Array<{
+            toolSlug: string;
+            status: "succeeded" | "failed" | "awaiting_approval" | "awaiting_oauth";
+            planId?: string;
+            runId?: string;
+            receiptId?: string;
+            output?: Record<string, unknown>;
+            error?: string;
+        }>;
+    }>;
+    /**
+     * Cloudflare Workflows (`step.do`, `step.waitForEvent`, `step.sleep`) Durable Orchestrator
+     * for multi-stage async Stripe v2 Cloud Provisioning & Vault Secret Injection.
+     */
+    startDurableWorkflow(ctx: ExecutionContext, params: {
+        provider?: string;
+        serviceRef?: string;
+        name?: string;
+        region?: string;
+    }): Promise<DurableWorkflow>;
+    advanceDurableWorkflow(ctx: ExecutionContext, workflowId: string, eventPayload?: Record<string, unknown>): Promise<DurableWorkflow>;
+    listDurableWorkflows(workspaceId: string): DurableWorkflow[];
+    /**
+     * Hybrid Semantic Vector + Bi-Temporal Recall (`@cf/baai/bge-base-en-v1.5` + Vectorize model).
+     */
+    searchMemoryHybrid(workspaceId: string, query: string, limit?: number): {
+        rankedMemories: Array<WorkspaceMemoryRecord & {
+            hybridScore: number;
+            vectorSimilarity: number;
+            lexicalOverlap: number;
+        }>;
+        vectorDimensions: number;
+        embeddingModel: string;
+        topScore: number;
+    };
+    /**
+     * Tamper-Evident R2 / WORM Audit Archive Bundle signed by the workspace's Ed25519 AgentIdentity.
+     */
+    exportTamperEvidentArchive(workspaceId: string): {
+        archiveId: string;
+        workspaceId: string;
+        storageTarget: string;
+        retentionMode: string;
+        exportedAt: string;
+        chainIntegrity: {
+            verified: boolean;
+            algorithm: string;
+            agentDid: string;
+            publicKeyFingerprint: string;
+            headMerkleHash: string;
+            bundleDigest: string;
+        };
+        counts: {
+            receipts: number;
+            governanceDecisions: number;
+            auditLogs: number;
+            temporalFacts: number;
+        };
+        merkleChain: {
+            sequence: number;
+            receiptId: string;
+            toolSlug: string;
+            prevHash: string;
+            entryHash: string;
+            createdAt: string;
+        }[];
+    };
+}